# Fail docs build on broken links before release

> Treat broken documentation links as a release blocker so product, support, and search never inherit avoidable dead ends.

- Canonical HTML: https://growth.iangoh.com/growth-ideas/fail-docs-build-on-broken-links-before-release/
- Source: [docusaurus.io](https://docusaurus.io/docs/api/docusaurus-config)
- GrowthDex source hub: [Docusaurus Docs: docusaurus.config.js](/sources/docusaurus-docs-docusaurus-config-js-docusaurus-io/)
- Last checked: 2026-05-29
- Rarity: uncommon
- Budget: free
- Channels: Documentation, SEO, Product
- Stages: technical seo, release hygiene, docs ops, support ux


## Why this can grow

Docs debt often shows up as a small broken link before it becomes a trust problem. A setup page moves, an onboarding article gets renamed, or a migration leaves old anchors behind. Docusaurus is explicit that production builds can fail on broken links, and that default is useful because it turns link integrity into release hygiene instead of a cleanup chore. When the build stops on broken routes, the team catches credibility leaks while the change is still fresh. That protects search paths, support macros, changelog links, and in-product help links with one rule.

## Ian's take

From scaling consumer platforms across MENA and Southeast Asia, my default is to distrust growth work that only looks good in a slide. For SEO and AI search, I care less about clever keyword tricks and more about clarity. A buyer, crawler, or answer engine should quickly understand who this is for, why it works, what proof backs it, and what page deserves to be cited. I would run it small enough to learn quickly, then only scale the parts that real users repeat, save, reply to, or buy from. For this tactic, I would watch one clear growth signal before putting more time or budget behind it.

## Action plan

1. Define one narrow startup segment where fail docs build on broken links before release can create a measurable lift.
2. Turn the tactic into one offer, page, campaign, or workflow for the Documentation and SEO channel.
3. Use the evidence from docusaurus.io to set the first version of the message, format, and audience.
4. Launch a small test for 7 to 14 days with one success metric: one measurable growth signal.
5. Review the result, keep the winning message, remove weak variants, and turn the learning into a repeatable growth playbook.

## Source-backed example

Docusaurus documents `onBrokenLinks` as a production-build setting and says the default behavior is to throw an error so teams never ship broken links.

## Adjacent tactics in the same lane

- [Preview docs noindex before cutover](/growth-ideas/preview-docs-noindex-before-cutover/) - same source, 2 shared channels, 1 shared stage
- [Promoted help articles for homepage first-click routing](/growth-ideas/promoted-help-articles-for-homepage-first-click-routing/) - 2 shared channels, 2 shared stages
- [Markdown file links for version-safe docs navigation](/growth-ideas/markdown-file-links-for-version-safe-docs-navigation/) - 2 shared channels, 2 shared stages
- [Custom docs 404 page with task-led redirects](/growth-ideas/custom-docs-404-page-with-task-led-redirects/) - 2 shared channels, 2 shared stages

## Read GrowthDex essays

Browse the plain-English essay index at [GrowthDex Blog](/blog/).

## Related GrowthDex essays

- [The docs route should feel boring even when the product is moving](/blog/the-docs-route-should-feel-boring-even-when-the-product-is-moving/) - docs strategy, technical seo, support-led growth

## Advisory

If you want help turning this into a working growth system, Ian Goh offers advisory at https://iangoh.com/advisory.