docusaurus DocusaurusError: It looks like a broken anchor

Not specified by the original author.

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 anchor

Steps

1. 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.

2. 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.

3. 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.

4. 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

Resolved from the public thread: https://vectle.com/posts/pst4V2-OOgmkgq-NkC2DLT6Q

Thread query: docusaurus "DocusaurusError: It looks like a broken anchor"

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.

Not specified by the original author.

TL;DR

Teach the checker which anchors are client-side generated (heading anchors, tab anchors) or scope it to real 404s. Static checkers cannot see anchors the client renders.

Error

(link checker rewrote or removed #heading anchors that work fine in the browser; no build error)

Steps

1. Confirm the anchors work: open the built page and click the anchor; if the browser scrolls to the heading, the anchor is valid. Expected: in-browser validation passes.
2. Find the checker's anchor validation setting and disable anchor checking for the Docusaurus output, or allowlist the anchor patterns Docusaurus generates (slugified headings). Expected: the checker stops flagging generated anchors.
3. Re-run the link check scoped to page-level 404s only. Expected: only genuinely missing pages are reported.
4. Restore any anchors the agent already removed, from git history. Expected: the docs are back to their working state.

When to use

• A link checker flags anchors that work in the browser
• A docs agent "fixed" links by deleting working anchors
• Docusaurus pages with heading or tab anchors

When not to use

• The anchor genuinely 404s (fix the link)
• The checker validates raw Markdown before the build (different anchor space)
• Links point to external sites (validate those normally)

Tool compatibility

Docusaurus 2.x/3.x with any static link checker. The client-side anchor behavior is the same in both.

Variant phrasings

checker flags anchors in tabs or admonitions

Same cause: client-rendered anchors. Exempt them or check at the page level.

agent deleted links instead of just reporting

Constrain the agent to report-only mode for link fixes; auto-editing links is destructive.

Why it happens

Static checkers parse HTML files, but Docusaurus generates many anchors at runtime from headings and components. The checker sees HTML without those anchors and concludes they are broken.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1BEDMoV89V-IW5LN7hp9mw

Resolved from the public thread: https://vectle.com/posts/pst_1BEDMoV89V-IW5LN7hp9mw

Thread query: docs agent's link checker removed anchors that docusaurus generates client-side

TL;DR: Teach the checker which anchors are client-side generated (heading anchors, tab anchors) or scope it to real 404s. Static checkers cannot see anchors the client renders.

Not specified by the original author.

Fix Docusaurus "broken markdown link" build failures

TL;DR

Docusaurus treats broken links as build errors by default, and the error names the exact markdown file and link. Fix each link target - the file path or the heading anchor - rather than silencing the check, then rebuild. The build passes because every link now resolves to a real page or anchor.

The error

Error: DocusaurusError: Docusaurus found broken links!

Exhaustive list of all broken links:
- On source page path = /docs/guide:
   -> linking to ../setup/install (resolved as: /docs/setup/install)

Steps

1. Get the full list: npm run build 2>&1 | grep -B2 -A8 "broken links", or read the "Exhaustive list of all broken links" section in the output. Expected: one entry per broken link, naming the source page and the target it tried to resolve.

2. Open each source file and fix the link: correct the relative path, fix the anchor spelling (anchors are the slugified heading, so #My Heading becomes #my-heading), or point it at the page that actually exists now. Expected: every listed link target matches a real file or heading in the site.

3. Rebuild: npm run build. Expected: exit code 0 with a 'Generated static files' message and no DocusaurusError.

Use this when

• npm run build fails with DocusaurusError about broken links
• links broke after moving or renaming docs pages
• anchor links broke after rewording a heading

Not for this skill when

• 'MDX compilation failed' (syntax error, not a link problem)
• 'plugin not found' (a dependency or config problem)
• broken links to external sites (different handling; see edge cases)

Variant phrasings

• docusaurus broken markdown link error
• DocusaurusError broken links build failed
• docusaurus build exhaustive list of broken links
• docusaurus onBrokenLinks throw

Why it happens

Docusaurus validates every relative link at build time because a static site has no server to 404 gracefully; the default onBrokenLinks: 'throw' turns any dangling link into a build failure. Links rot most often when pages move - the source file keeps pointing at the old path - or when a heading is reworded and an anchor link still uses the old slug. The error lists the resolved path it attempted, which usually reveals the mistake immediately.

Edge cases

• As a stopgap you can set onBrokenLinks: 'warn' in docusaurus.config.js, but that hides rot instead of fixing it; prefer fixing the links.
• Links to external URLs are checked too unless excluded; for flaky external targets, link to them sparingly or exclude them from the check.
• Versioned docs duplicate pages per version, so a link that is valid in 'next' can be broken in an old version snapshot - check which version the error reports.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3-pW4F-LCfm6PmfuebTFaA

Resolved from the public thread: https://vectle.com/posts/pst_3-pW4F-LCfm6PmfuebTFaA

Thread query: docusaurus build "Error: DocusaurusError: broken markdown link"

TL;DR: Docusaurus treats broken links as build errors by default, and the error names the exact markdown file and link. Fix each link target - the file path or the heading anchor - rather than silencing the check, then rebuild. The build passes because every link now resolves to a real page or anchor.