docusaurus build Error: DocusaurusError: broken markdown link

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.

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.

Fix Docusaurus "MDX compilation failed" unexpected character errors

TL;DR

MDX treats curly braces as JavaScript expressions, so a literal { or } in prose (or one unclosed code fence) breaks parsing at the reported line. Wrap literal braces in code spans or escape them as {'{'} {'}'} style expressions, close the fence, then rebuild. The file compiles because the parser no longer sees stray expression syntax.

The error

[MDXCompilationError] Docusaurus MDX loader failed to parse markdown content in docs/guide.md:
Unexpected character `{` (1:42)

Steps

1. Read the error: it names the file and the exact line and column of the offending character. Expected: you can point at the specific character in the source file.

2. Fix the character: wrap literal braces in backtick code spans, or escape them as MDX expressions like {'{'} and {'}'}. Bare braces only survive inside code spans, fenced code blocks, or real JSX expressions. Expected: no bare curly braces remain in prose.

3. Check for an unclosed code fence above the error line: one missing closing fence makes the rest of the file parse as code and the error surfaces far from the real problem. Count the fences. Expected: every opening fence has a matching closing fence.

4. Rebuild: npm run build. Expected: MDX compiles the file and the build continues past it.

Use this when

• MDXCompilationError naming a file, line, and column
• docs showing JSON snippets or template syntax with literal braces
• a page that broke right after a code block was edited

Not for this skill when

• 'broken markdown link' (the file parses fine; a link target is wrong)
• 'plugin not found' (dependency/config problem)
• a blank page with no build error (rendering problem, not a parse problem)

Variant phrasings

• docusaurus MDX compilation failed
• docusaurus unexpected character MDX
• docusaurus could not parse markdown content
• mdx loader failed docusaurus curly brace

Why it happens

Docusaurus pages are MDX, which is Markdown plus JSX: the compiler scans prose for { } expression boundaries and JSX-style tags. A literal brace in normal text - common in JSON examples, config snippets, or template placeholders - opens an expression the parser cannot close, so it reports an unexpected character. An unclosed code fence is the sneakier variant: everything after it is treated as code until the next fence, and the parse error lands far from the missing fence.

Edge cases

• import and export statements are only allowed at the top of an MDX file; one buried mid-page throws a different MDX error.
• JSX-style tags in prose must be valid or wrapped in code spans; an unclosed tag swallows the following paragraphs.
• If a page needs lots of literal braces, prefer a fenced code block over inline escapes - it is easier to read and cannot break parsing.

Provenance

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

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

Thread query: docusaurus "MDX compilation failed" unexpected character error

TL;DR: MDX treats curly braces as JavaScript expressions, so a literal { or } in prose (or one unclosed code fence) breaks parsing at the reported line. Wrap literal braces in code spans or escape them as {'{'} {'}'} style expressions, close the fence, then rebuild. The file compiles because the parser no longer sees stray expression syntax.