Skip to content

feat(cli): write-heading-ids CLI now supports the --syntax and --migrate options #11777

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
slorber merged 17 commits into from
Mar 5, 2026
Merged

feat(cli): write-heading-ids CLI now supports the --syntax and --migrate options #11777

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
c1027fd
add scaffolding for mdx comment syntax heading ids
slorber Feb 27, 2026
8cd2bec
add basic impl
slorber Feb 27, 2026
033a55a
add tests
slorber Feb 27, 2026
6011e4f
add support for mdx syntax
slorber Mar 5, 2026
b5f159c
add support for mdx headingId syntax
slorber Mar 5, 2026
bde54d1
add missing test case
slorber Mar 5, 2026
27cc448
add missing test case
slorber Mar 5, 2026
efd6e72
extract headingId code to separate markdownHeadingIdUtils.ts
slorber Mar 5, 2026
d5cdc93
dedent tests
slorber Mar 5, 2026
16424d0
wire to cli
slorber Mar 5, 2026
234b9ea
wire to cli
slorber Mar 5, 2026
2c36c7f
Add ability to migrate from one syntax to another without re-generati…
slorber Mar 5, 2026
668a690
add --migrate CLI option
slorber Mar 5, 2026
3884f59
forbid migrate + overwrite
slorber Mar 5, 2026
e96984d
cli docs update
slorber Mar 5, 2026
ab720e7
update docs
slorber Mar 5, 2026
db649b6
empty
slorber Mar 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
add support for mdx syntax
  • Loading branch information
@slorber
slorber committed Mar 5, 2026
commit 6011e4f205322b1a91568b0b84997b7efc821b50
2 changes: 1 addition & 1 deletion packages/docusaurus-utils/src/__tests__/markdownUtils.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1981,7 +1981,7 @@ describe('writeMarkdownHeadingId', () => {

## abc {/* #abc-1 */}

### Hello world {/* #hello-world */}}
### Hello world {/* #hello-world */}

\`\`\`
# Heading in code block
Expand Down
10 changes: 10 additions & 0 deletions packages/docusaurus-utils/src/markdownUtils.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ export function parseMarkdownHeadingId(heading: string): {
/** The heading ID. e.g. `some-heading` */
id: string | undefined;
} {
// Classic syntax: {#my-id}
const customHeadingIdRegex = /\s*\{#(?<id>(?:.(?!\{#|\}))*.)\}$/;
const matches = customHeadingIdRegex.exec(heading);
if (matches) {
Expand All @@ -40,6 +41,15 @@ export function parseMarkdownHeadingId(heading: string): {
id: matches.groups!.id!,
};
}
// MDX comment syntax: {/* #my-id */}
const mdxCommentHeadingIdRegex = /\s*\{\/\*\s*#(?<id>\S+)\s*\*\/\}$/;
const mdxMatches = mdxCommentHeadingIdRegex.exec(heading);
if (mdxMatches) {
return {
text: heading.replace(mdxMatches[0]!, ''),
id: mdxMatches.groups!.id!,
};
}
return {text: heading, id: undefined};
}

Expand Down