Skip to content

Docs: Add blank lines inside admonitions - #2128

Open
vzaidman wants to merge 2 commits into
mainfrom
export-D127668483
Open

vzaidman wants to merge 2 commits into
mainfrom
export-D127668483

Conversation

@vzaidman

Copy link
Copy Markdown
Contributor

Summary:
Adds a blank line after each opening :::note/:::info/:::caution and before each closing :::. Without them, prettier treats the closing ::: as part of a preceding list item and indents it, which breaks the admonition. Docusaurus recommends these blank lines when formatting Markdown with prettier.

This prepares the docs for formatting with prettier in the next diff. No rendered changes.

Changelog: [Internal]

Differential Revision: D127668483

Summary:
Extracts the markdown linting React Native uses at Meta into Metro's OSS setup, and fixes the existing issues.

- `yarn lint-markdown` runs `markdownlint-cli2` on `docs/*.md`. It runs on GitHub CI (`build-test-and-deploy.yml`), in the internal OSS Metro tests (`test-oss-metro-legocastle.sh`) and in `yarn test`.
- `.markdownlint-cli2.jsonc` enables the same rules as React Native's `.markdownlint-cli2.mjs`, e.g. `heading-increment`, `link-fragments` and `no-trailing-punctuation`. React Native's `relative-links` custom rule is not used: it includes the HTML of headings such as `` `unstable_middleware` <div class="label experimental">Experimental</div> `` in their anchors, so it rejects valid links like `./Configuration.md#unstable_middleware-experimental`. Links between pages are checked by the website build (`onBrokenLinks`/`onBrokenAnchors: throw`).

Fixes:
- `heading-increment`: "Merging Example" in `Configuration.md`, and the top-level sections of `LocalDevelopment.md` and `Troubleshooting.md`, are one level higher.
- `no-space-in-code`: the `schemeResolvers` type is a single code span, followed by a link to `CustomResolver`.
- `no-trailing-punctuation`: "File extensions are important!" in `PackageExports.md` loses the "!".

Heading anchors are unchanged.

Changelog: [Internal]

Differential Revision: D127663612
Summary:
Adds a blank line after each opening `:::note`/`:::info`/`:::caution` and before each closing `:::`. Without them, prettier treats the closing `:::` as part of a preceding list item and indents it, which breaks the admonition. Docusaurus recommends these blank lines when formatting Markdown with prettier.

This prepares the docs for formatting with prettier in the next diff. No rendered changes.

Changelog: [Internal]

Differential Revision: D127668483
@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Oct 29, 2026
@meta-codesync

meta-codesync Bot commented Oct 29, 2026

Copy link
Copy Markdown
Contributor

@vzaidman has exported this pull request. If you are a Meta employee, you can view the originating Diff in D127668483.

meta-codesync Bot pushed a commit that referenced this pull request Oct 29, 2026
Summary:

Adds a blank line after each opening `:::note`/`:::info`/`:::caution` and before each closing `:::`. Without them, prettier treats the closing `:::` as part of a preceding list item and indents it, which breaks the admonition. Docusaurus recommends these blank lines when formatting Markdown with prettier.

This prepares the docs for formatting with prettier in the next diff. No rendered changes.

Changelog: [Internal]

Differential Revision: D127668483
meta-codesync Bot pushed a commit that referenced this pull request Oct 29, 2026
Summary:

Adds a blank line after each opening `:::note`/`:::info`/`:::caution` and before each closing `:::`. Without them, prettier treats the closing `:::` as part of a preceding list item and indents it, which breaks the admonition. Docusaurus recommends these blank lines when formatting Markdown with prettier.

This prepares the docs for formatting with prettier in the next diff. No rendered changes.

Changelog: [Internal]

Differential Revision: D127668483
@github-actions

Copy link
Copy Markdown

Metro review: Looks good

Risk: low · Commit: caee13b · 3 commands run

This PR adds a blank line after each opening :::note/:::info/:::caution and before each closing ::: in six docs pages, so a later prettier pass won't indent a closing fence into the list item before it. Every admonition under docs/ now has these blank lines, and running prettier on ModuleAPI.md showed the problem the PR describes and that the change fixes it. There are no code changes, and I found no problems.

No findings.

Verified
  • ✅ Grep for ^\s*::: across worktree/docs with 1 line of context — Every opening and closing admonition fence in docs/*.md, including Resolution.md, which this PR doesn't touch, now has a blank line inside it, so the change is complete.
  • ✅ yarn -s prettier --no-config --ignore-path=/dev/null --parser markdown docs/ModuleAPI.md (base vs head), grep ':::' — At the base, prettier indents the closing ::: of the :::info that ends in a list item by 3 spaces (line 58), which breaks the admonition. At the head it stays at column 0, as the description says.
  • ✅ yarn prettier --ignore-path=/dev/null --check docs/{ModuleAPI,SourceMapFormat,Configuration,PackageExports,Bundling,GettingStarted}.md (base and head) — Both base and head report clean, so the repo's own prettier config doesn't format these files yet. The real formatting happens in the follow-up diff.

Not run: I didn't run a Docusaurus website build to confirm that the rendered output is identical. Blank lines inside admonitions are the documented Docusaurus form, so I don't expect any rendering change. No benchmarks were needed, since only Markdown docs change. Two commands that used shell variables or several chained operations were blocked by the session's no-approval policy, so I reran them in simpler forms.

Automated review by Claude. Advisory only: it never approves or blocks, and a maintainer makes the call.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. meta-exported needs-meta-import

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant