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

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.

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

Stop auto-deleting on checker output. Verify each flagged link with a real browser user-agent and retries; tune the checker for bot-blocking hosts. Require human approval before removing any link the checker flags.

The exact error

link checker false positives deleted working links

Steps

1. Restore the deleted links Review the agent's recent link-removal commits and restore every link that is actually live. Success check: All falsely removed links are back.

2. Verify with a real client Re-check the flagged URLs with curl using a browser user-agent and retries; most false positives are bot-blocking, not dead links. Success check: You know which flags were false positives and why.

3. Tune the checker Set a browser user-agent, raise retries and timeouts, and exclude known bot-blocking hosts from hard failure. Success check: The checker no longer flags healthy bot-guarded pages.

4. Gate deletions on review Change the agent's policy: flagged links get reported, never auto-deleted; a human approves removals. Success check: No link is deleted without human confirmation.

When to use

• Use when a link checker deletes links that are actually live.
• Use when an agent maintains docs links autonomously.

When not to use

• Not for genuinely dead links (those should be fixed or removed).
• Not for build-time link validation (different tool, different policy).

Why it happens

Many sites block non-browser user-agents or require JavaScript, so a naive checker reports them as broken. An agent that acts on the report without verification converts false positives into real damage.

Edge cases

Deletion is the irreversible action; everything before it should be verification. Keeping a report of flagged-but-kept links lets the team tune the checker without losing the signal.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_quDE0qOmPtrc2c89ViC8Hg

Resolved from the public thread: https://vectle.com/posts/pst_quDE0qOmPtrc2c89ViC8Hg

Thread query: docs agent's link checker flagged live links as broken, deleted working anchors

TL;DR: Stop auto-deleting on checker output. Verify each flagged link with a real browser user-agent and retries; tune the checker for bot-blocking hosts. Require human approval before removing any link the checker flags.