Mintlify docs monitoring

Mintlify is a hosted documentation platform driven by MDX files and a single configuration file that defines navigation, redirects and theming. Because the navigation is declared explicitly, the most common Mintlify problems come from the configuration drifting away from the content.

How Mintlify sites typically break

Navigation is the source of truth for reachability. Pages exist when their MDX files exist, but they are only linked when they appear in the navigation groups of the config file. A page removed from navigation but not deleted becomes an orphan: still deployed, possibly still in the sitemap, reachable only from search results.

Renamed headings break anchors. Heading ids are typically generated from the heading text, so cross-page links of the form /api/auth#refresh-tokens break as soon as the heading is edited; check Mintlify's docs for its exact slug rules.

API reference pages generated from OpenAPI change URLs when the spec changes. Operation-based pages take their paths from the spec, so renaming an operation can move a page that other docs link to.

Migrating to Mintlify changes every URL. Teams moving from Docusaurus, GitBook or ReadMe usually end up with a different path structure. Without redirects, every inbound link and every indexed URL from the old site returns 404.

External links rot. Links to third-party docs, GitHub files and blog posts are not re-checked after publishing.

What Mintlify's own checks catch, and what they miss

• The Mintlify CLI offers a broken-link check for internal links in your content; see Mintlify's CLI docs for the current command and whether anchors are covered.
• Preview deployments surface build errors in MDX.
• It misses: external links, redirect chains and loops, live-site failures, anchors targeted from other sites, sitemap drift, orphan pages created by navigation edits, soft 404s, duplicate titles, and canonical problems.

Setting up redirects on Mintlify

Redirects are configured as a top-level redirects array in docs.json:

{
  "redirects": [
    { "source": "/docs/old-page", "destination": "/docs/new-page" },
    { "source": "/guides/legacy", "destination": "/guides/current" }
  ]
}

Each entry may set permanent (default true, a 308; false gives a 307), and sources support :slug* wildcards and partial wildcards. The migration redirect checker generates this format from an old sitemap, and the redirect rules cheat sheet covers the hosting-level alternatives.

How PathIntact monitors a Mintlify site

• Detection: the <meta name="generator" content="Mintlify"> tag plus Mintlify asset hosts and script paths. Detected sites default to the Mintlify redirect snippet.
• Render mode: auto. Pages are read statically; a page is rendered in Chromium only when the static HTML looks like an empty application shell.
• Navigation and orphans: links inside <nav> and sidebars count as inbound links, so a page removed from navigation is reported as an orphan if it is still in the sitemap.
• Sitemap: hosted Mintlify sites typically publish a sitemap.xml. PathIntact seeds from it when present and reports URLs that return non-200, noindex pages listed in the sitemap, and drift between crawls.
• Anchors and API pages: every #fragment link is checked against the target page's element ids, including generated API reference pages.

Check my docs