You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This migrates our website to the new {/* #headingId */} syntax.
This disables the markdown.mdx1Compat.headingIds compat layer on our website, since we no longer need it. To keep dogfooding the classic syntax within MDX docs, I kept a few cases of this syntax, using explicit escaping (\{#headingId}).
Note: the classic syntax ({#headingId}) remains supported and is not deprecated. It is commonly used in CommonMark tools, so it makes sense to keep using it for .md docs, although we don't recommend it for .mdx docs.
This also updates the Crowdin config to upgrade to their latest MDX parser. They considered my feedback (preventing {/* #headingId */} from being translated), so can finally do this migration. As part of this PR, I'm also transitioning all the existing MDX files on Crowdin to that new parser, so that all MDX files use the exact same parser (otherwise, they preserve the parser that got set at their initial upload time).
Test Plan
CI + Argos
Crowdin: local tests using Crowdin CLI + building the localized website locally + checking pages remain translated
slorber
changed the title
chore(website): update/dogfood heading id syntax on our site + upgrade Crowdin MDX parser version
chore(website): migrate MDX heading ids to comment syntax + upgrade Crowdin parser version
Mar 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ArgosAdd this label to run UI visual regression tests. See argos.yml GH action.CLA SignedSigned Facebook CLApr: documentationThis PR works on the website or other text documents in the repo.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
slorber
changed the title
Motivation
Follow up on:
write-heading-idsCLI now supports the--syntaxoption #11777headingIdbased on MD/MDX comments #11755This migrates our website to the new
{/* #headingId */}syntax.This disables the
markdown.mdx1Compat.headingIdscompat layer on our website, since we no longer need it. To keep dogfooding the classic syntax within MDX docs, I kept a few cases of this syntax, using explicit escaping (\{#headingId}).Note: the classic syntax (
{#headingId}) remains supported and is not deprecated. It is commonly used in CommonMark tools, so it makes sense to keep using it for.mddocs, although we don't recommend it for.mdxdocs.This also updates the Crowdin config to upgrade to their latest MDX parser. They considered my feedback (preventing
{/* #headingId */}from being translated), so can finally do this migration. As part of this PR, I'm also transitioning all the existing MDX files on Crowdin to that new parser, so that all MDX files use the exact same parser (otherwise, they preserve the parser that got set at their initial upload time).Test Plan
CI + Argos
Crowdin: local tests using Crowdin CLI + building the localized website locally + checking pages remain translated
Test links
https://deploy-preview-11779--docusaurus-2.netlify.app/
Related issues/PRs
Slightly related to this issue: #11628