# 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

```text
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