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.
Why this can grow a startup
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.
Company 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.
Source and metric
Source: Docusaurus Docs: docusaurus.config.js
Docusaurus defaults `onBrokenLinks` to `throw`, and broken-link detection runs on production builds.
Source discovered: May 29, 2026
When to use it
Use this when Documentation, SEO, Product is relevant to technical seo, release hygiene, docs ops and you can run a bounded test with a free budget.
When not to use it
Do not use it as a substitute for customer evidence, a clear owner, or a measurable stop condition. Local platform rules and market behavior still need checking.
Founder checklist
- Read Docusaurus Docs: docusaurus.config.js and identify what is directly supported.
- Choose one channel context: Documentation, SEO, Product.
- Define the test around Docusaurus defaults `onBrokenLinks` to `throw`, and broken-link detection runs on production builds..
- Set an owner, evidence window, and stop condition before launch.
Explore the context
Apply this with an operator
Turn isolated search tactics into a crawlable visibility system tied to demand and proof.