docs agent's link checker removed anchors that docusaurus generates client-side
Fixes link checkers that flag and remove anchors Docusaurus generates client-side. Use when valid anchors are reported broken after a docs-agent link pass. Not for genuinely broken links.
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
- 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.
- 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.
- Re-run the link check scoped to page-level 404s only. Expected: only genuinely missing pages are reported.
- 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