no-deprecated-heading-id-syntax
Disallow deprecated {#my-id} heading syntax in .mdx files and prefer the Docusaurus 3.10 MDX comment form.
Targeted pattern scopeโ
This rule focuses on .mdx content files.
It reports headings that still use the legacy Docusaurus suffix form:
## My Heading {#my-id}
What this rule reportsโ
This rule reports deprecated heading ID syntax in .mdx files and expects the newer MDX comment form:
## My Heading {/* #my-id */}
Why this rule existsโ
Docusaurus 3.10 recommends replacing the old proprietary heading ID syntax with a native MDX comment form.
That newer syntax is more compatible with external tools and aligns with the write-heading-ids --syntax mdx-comment --migrate guidance from the release notes.
โ Incorrectโ
## API Surface {#api-surface}
โ Correctโ
## API Surface {/* #api-surface */}
Behavior and migration notesโ
This rule autofixes the deprecated heading suffix to the MDX comment form in .mdx files.
It intentionally ignores fenced code blocks so examples and snippets are not touched.
ESLint flat config exampleโ
import docusaurus2 from "eslint-plugin-docusaurus-2";
export default [docusaurus2.configs["strict-mdx-upgrade"]];
When not to use itโ
Do not use this rule if your migration plan still depends on the legacy syntax, keep the rule off until you are ready to standardize on strict MDX.
Rule catalog ID: R115