chore(mdx): enable the v4 strict MDX flag and guard admonition syntax

[thetaPC]

Issue URL: internal

What is the current behavior?

Docusaurus still applies the MDX v1 compatibility shims: mdx1Compat.comments, .admonitions and .headingIds all default to true. Nothing in the repo relies on them any more, so they are no-ops that hide regressions. A page reintroducing <!-- comment -->, :::note Title or {#heading-id} builds fine today and breaks on the v4 upgrade instead.

What is the new behavior?

future.v4.mdx1CompatDisabledByDefault: true, which flips all three to false. One functional line; the rest of that diff moves the existing future comment so each key is documented above itself.

Two of the three now fail the build outright. The third does not: :::note My Title stops being a directive and renders as literal :::note text on the page, with no warning and a successful build. A new check-admonitions action covers that one case, on the files each PR changes.

Does this introduce a breaking change?

• Yes
• No

Other information

Verified on a throwaway PR against this branch, #4724, which plants one legacy title alongside four forms that must not be flagged. The failing check run reports only the legacy one, and the annotation lands on the offending line in the Files changed tab. The bracketed, untitled, fenced and inline-code forms in the same file are correctly ignored.

On this PR the check reports No MDX files changed, since it touches none.

Docusaurus's own unusedDirectives warning is already enabled and catches :::typo, but it cannot catch this: it visits directive nodes, and :::note My Title parses to a plain paragraph. There is no node to visit, which is why the check has to work on the raw text before parsing.

Both locales build with 716 pages each and 1029 warnings, identical to the same tree with the flag off. The ja tree is pulled from translation/jp at build time rather than living here, so no CI covers it; the 267 files it fetched are clean.

How to test

1. npm run build and confirm both locales complete
2. Add <!-- test --> to any page under docs/ and rebuild. It should now fail with Could not parse expression with acorn or Unexpected character !, where before it built silently. Revert.

Archived v5 to v7 are not built by default. To check them:

1. Set versions.json to ["v8", "v7", "v6", "v5"]
2. Run npx docusaurus clear (clearing only .docusaurus leaves the rspack cache)
3. Run npm run build
4. Revert

All five versions build clean.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
ionic-docs	Ready	Preview	Sep 10, 2026 6:49pm UTC