docusaurus build "Error: DocusaurusError: broken markdown link"

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