chore(deps): migrate to Docusaurus 3.10.1#2045
Merged
Merged
Conversation
dgozman
approved these changes
Jun 3, 2026
Bump all @docusaurus/* packages from 3.8.1 to 3.10.1 and rename the renamed-in-3.10 future flag experimental_faster -> faster.
Docusaurus 3.10 with future.v4 disables the mdx1Compat shims, so the classic
`{#id}` heading-id syntax is parsed as a (failing) MDX expression. Emit the
ids as MDX comments `{/* #id */}` instead, which is valid MDX as-is and which
Docusaurus extracts into identical anchor ids (no links change).
- generator.js emits `{/* #id */}`; no post-processing/escaping needed.
- Codemod existing committed .mdx (api docs + community page) to the new form.
- Drop the stray HTML comment from the stable webview2 snapshots (already
removed upstream in microsoft/playwright), so no HTML-comment handling is
needed either.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Summary
@docusaurus/*packages from 3.8.1 to 3.10.1.markdown.mdx1Compatshims (whichfuture.v4disables by default).Background
3.10.1 surfaces a build break because
future.v4: truenow disables the MDX1 compatibility shims that 3.8.1 enabled by default: explicit heading ids### Heading {#id}get parsed as JS expressions →Could not parse expression with acorn.Rather than re-enable the shim via config, the generator now emits the heading id in the MDX comment form
{/* #id */}, which is valid MDX as-is and which Docusaurus extracts into the same anchor ids (no links change). No post-processing/escaping step is needed.Existing committed
.mdx(api docs, versioned_docs, and the hand-written community page) were migrated to the new form with a one-time codemod. Thefuture.experimental_fasterflag was also renamed tofuture.faster(renamed in 3.10).The only other MDX incompatibility was a stray HTML comment in the webview2 guide; it was removed upstream (microsoft/playwright#41122) and dropped from the stable snapshots here, so no HTML-comment handling is needed.
Test plan
npm run build(nodejs/python/java/dotnet) all succeed with nomdx1Compatconfig.id=screencast-hide-actionsin built HTML); no{#...}leak into rendered text.tscpasses.