chore(docs): MDX 3 compat (HTML→JSX comments, drop {#anchor} in introduction) (#41 follow-up)#182
Merged
Merged
Conversation
…#anchor} in introduction) Mechanical compatibility pass so the docs/ tree compiles under MDX 3 (the parser used by Docusaurus 3 — needed by the upcoming docs-site work tracked in #41). ## Changes - `<!-- ... -->` → `{/* ... */}` across 8 files. MDX 3 parses HTML comments as JSX expressions and fails; the JSX comment form is the documented replacement. Inner content is unchanged. Rendered output is unaffected (comments are not visible). - `introduction.md`: drop the two explicit `{#anchor}` IDs on H2 headings (Fast Track, Coming from Cake). Docusaurus auto-generates slugs from heading text, so inbound `#fast-track` / `#coming-from-cake` fragment links will need a one-time refresh if anything points at them. Nothing in-repo does today. ## Why now These touch-ups are needed before any Docusaurus 3 build can succeed, regardless of where the rendered site is hosted. Pre-landing them so the downstream docs-site work (#41) can pull from main without local patches. Refs #41
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
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.
Summary
Pre-landing the mechanical MDX-compat changes to `docs/` so the Docusaurus 3 build for #41 can run against `main` without local patches. Splits out cleanly from #181 (closed; CF Pages was the wrong architecture).
Changes (8 files)
Why MDX 3 needs this
Docusaurus 3 (latest) parses every `.md` / `.mdx` file through MDX 3. MDX 3 treats `` as an attempted JSX tag and errors out (it's not valid JSX). The documented replacement is `{/* ... */}` — same effect (invisible in output), MDX-parsable. The anchor-ID removal is for the same reason — MDX 3 sees `{#fast-track}` after a heading and tries to parse it as a JS expression; `#` isn't valid in expressions, so it fails. Slugs auto-generate from heading text instead.
Verified
Follow-up
Closes
🤖 Generated with Claude Code