chore(i18n, 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 on this branch 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?

The jp companion to #4723. 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. The check-admonitions action covers that one case, on the files each PR changes.

Does this introduce a breaking change?

• Yes
• No

Other information

The action is byte-identical to the one on main, so it is not re-tested here. Its behavior was proven on #4724, a throwaway PR that 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. This branch has 0 legacy admonition titles, so the check lands green, and on this PR it reports No MDX files changed.

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.

The build produces 744 pages and 407 warnings, identical to the same tree with the flag off: nothing introduced, nothing resolved.

How to test

1. npm run build and confirm it completes
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. They were verified with the flag on in #4717 against content identical to this branch, building 460 v5, 307 v6, 310 v7 and 326 v8 pages. To repeat it:

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

[vercel]

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

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