docusaurus "DocusaurusError: It looks like a broken anchor"
Fixes the Docusaurus broken-anchor build error from bad in-page links. The skill shows how to find the offending anchor, match it to the real heading slug, and handle anchors in translated or versioned docs. It explains Docusaurus heading slug rules.
TL;DR
Fix the anchor to match the actual heading slug, or remove it. Docusaurus slugifies headings: lowercase, spaces to hyphens, punctuation stripped. Check anchors in versioned and translated docs too, since slugs can differ per locale.
The exact error
DocusaurusError: It looks like a broken anchorSteps
Find the reported anchor Run the build and copy the file and anchor from the error. Open the file and locate the markdown link pointing at it. Success check: You have the file, the link, and the anchor text that failed.
Compute the real slug Find the target heading and apply Docusaurus slug rules: lowercase, spaces become hyphens, most punctuation removed. Compare against the link. Success check: You can see the mismatch: a renamed heading, wrong case, or leftover punctuation.
Fix the link Update the anchor in the link to the computed slug, or retarget the link at the correct heading. Success check: The link anchor matches the heading slug exactly.
Rebuild and scan versions Run the build and confirm no broken-anchor errors. Repeat for versioned docs and each locale. Success check: Clean build across all versions and locales with working in-page jumps.
When to use
- Use when Docusaurus fails the build on a broken anchor.
- Use when an agent rewrites headings and needs to keep anchors in sync.
When not to use
- Not for broken page links (different error: broken markdown link).
- Not for anchors to external sites (Docusaurus only validates internal anchors).
Why it happens
Docusaurus validates every #anchor against the slugs of headings on the target page at build time. Renaming a heading changes its slug, which silently breaks every link that pointed at the old anchor, and the build fails instead of shipping a dead jump.
Edge cases
Custom heading IDs with {#custom-id} bypass slug computation; use them for headings that get renamed often. Translated docs generate their own slugs from translated headings, so an anchor that works in English can break in another locale.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst4V2-OOgmkgq-NkC2DLT6Q