Docusaurus docs monitoring

Docusaurus is a static site generator for documentation with first-class support for versioned docs, sidebars and MDX. Because it pre-renders every page, most of its problems are not build failures but drift on the live site: renamed headings, removed versions, sidebar changes that strand pages, and migrations that change URLs.

How Docusaurus sites typically break

Heading anchors change when headings change. Docusaurus generates the id of each heading from its text (and supports explicit ids with ## Heading {#custom-id}; TODO(verify): exact slugging rules for punctuation and duplicates). Rename "Install the CLI" to "Installing the CLI" and every link to #install-the-cli, including links from other pages and from external sites, silently points at nothing. Docusaurus can warn about anchors between its own pages at build time, but not about anchors targeted from outside the build.

Versioned docs multiply every URL. With versioning enabled, /docs/ (current), /docs/next/ and /docs/2.1/ may all exist. Pages in the latest version often keep links into an older version after a copy-paste, and old versions keep links to pages that no longer exist in the current version. Search engines then split ranking between near-identical pages unless canonicals are set deliberately.

Sidebars decide what is reachable. A page removed from sidebars.js but left in the docs folder still builds and still appears in the sitemap, but nothing links to it: an orphan page that readers reach only from search.

Migrations change URLs. Moving from another generator to Docusaurus, or changing the routeBasePath, changes every URL. Without redirects the old URLs return 404 while search engines still send traffic to them.

External links rot. Docusaurus does not check external links at build time (its broken-link options cover internal links and anchors only; verified 2026-09-17 against the config reference), so links to vendor docs, RFCs and blog posts break over months without anyone noticing.

What the Docusaurus build catches, and what it misses

• onBrokenLinks (default throw) fails the build for internal links to pages that do not exist; markdown.hooks.onBrokenMarkdownLinks (default warn, replaces the deprecated onBrokenMarkdownLinks since v3.9) reports broken Markdown link URLs. Verified 2026-09-17.
• onBrokenAnchors (default warn) reports links to missing anchors declared with the Heading component within the built site. Verified 2026-09-17.
• It misses: external links, redirects and redirect chains, anchors targeted from other sites or from old versions, pages that work in the build but fail on the CDN, sitemap drift between deploys, orphan pages (a page with no inbound links still builds fine), soft 404s, duplicate titles across versions, and anything that changes after deploy.

Setting up redirects on Docusaurus

Docusaurus ships an official redirects plugin, @docusaurus/plugin-client-redirects. It writes extra HTML pages that redirect with JavaScript at build time rather than sending HTTP redirects, which is fine for readers but weaker for search engines than a 301 from your host. Verified 2026-09-17 against the plugin reference.

// docusaurus.config.js
plugins: [
  [
    '@docusaurus/plugin-client-redirects',
    {
      redirects: [
        { from: '/docs/old-page', to: '/docs/new-page' },
        { from: ['/docs/legacy-a', '/docs/legacy-b'], to: '/docs/new-page' },
      ],
    },
  ],
],

from accepts a string or an array ({ to: string; from: string | string[] }). TODO(verify): how trailingSlash interacts with generated redirect paths.

If you deploy to Vercel, Netlify or Cloudflare Pages, prefer HTTP redirects in vercel.json or _redirects in addition to (or instead of) the plugin. The redirect rules cheat sheet has every format, and the migration redirect checker generates them from your old sitemap.

How PathIntact monitors a Docusaurus site

• Detection: the <meta name="generator" content="Docusaurus ..."> tag, the #__docusaurus mount element and Docusaurus asset paths (verified 2026-09-17 against docusaurus.io, confidence 1.0). Detected sites default to the Docusaurus redirect snippet format in fix suggestions.
• Render mode: auto, which almost never needs a browser for Docusaurus because pages are pre-rendered. If a page is an empty shell (fewer than 200 words and only the mount element), it is rendered in Chromium.
• Version handling: paths like /docs/1.2/ and /docs/next/ are detected as a /docs/{version}/ pattern. Pages in the latest version that link into older versions are reported as old-version links (navigation and version switchers are ignored). Canonicals that point across versions are flagged.
• Sitemap: Docusaurus emits sitemap.xml TODO(verify): via @docusaurus/plugin-sitemap, included in the classic preset. PathIntact seeds the crawl from it and reports sitemap URLs that return non-200, noindex pages listed in the sitemap, drift between crawls, and orphan pages listed in the sitemap that nothing links to.
• Anchors: every #fragment link is compared with the ids on the target page, case-sensitively, with hints when only the case or the slug format differs.

Check my docs