MkDocs and Material docs monitoring

MkDocs builds static HTML from Markdown with a navigation tree declared in mkdocs.yml. Material for MkDocs adds search, tabs and instant navigation, and mike adds versioned deployments. The static output is easy to crawl; the breakage is mostly about navigation drift, heading slugs and versions.

How MkDocs sites typically break

Pages not in nav become orphans. MkDocs still builds a page that is missing from nav and reports "The following pages exist in the docs directory, but are not included in the 'nav' configuration" (validation.nav.omitted_files, an error in --strict mode; verified 2026-09-17), but nothing links to it, so it only surfaces from search and slowly loses ranking.

Heading slugs change with heading text. The toc extension generates ids from heading text TODO(verify): default slugify function and the toc slugify option in Material. Cross-page anchor links break when headings are edited, and Material's permalinks encourage people to copy those links.

Versioned deployments with mike multiply URLs. Each version has its own tree, typically /1.4/, /2.0/ and an alias like /latest/ TODO(verify). Pages copied into a new version keep links into the old one, and old versions often lack canonical tags pointing at the latest.

use_directory_urls changes every URL. It defaults to true; toggling it moves pages from /page.html to /page/ or back. Old links and indexed URLs need redirects.

Instant navigation can mask errors. Material's instant loading fetches pages with JavaScript; a broken link may show a client-side error rather than a server 404 TODO(verify), so readers and simple checkers see different things.

What the MkDocs build catches, and what it misses

• mkdocs build --strict halts on any warning, including validation.links.anchors, validation.links.unrecognized_links, validation.links.absolute_links and validation.nav.not_found (each defaults to warn). Verified 2026-09-17 against the configuration reference.
• Warnings for documentation files not included in nav.
• It misses: external links, anchors targeted from other sites, redirect chains, sitemap drift, soft 404s, duplicate titles across versions, and everything that happens on the live host.

Setting up redirects on MkDocs

The mkdocs-redirects package (plugin name redirects) creates HTML redirect pages at build time (verified 2026-09-17):

# mkdocs.yml
plugins:
  - redirects:
      redirect_maps:
        old/page.md: new/page.md
        guides/legacy.md: guides/current.md

Keys are the old Markdown paths relative to docs_dir; values are new Markdown paths or external URLs. These are meta-refresh redirects, which readers follow but search engines treat less reliably than HTTP 301s. If the site is hosted on GitHub Pages you are limited to this approach; on Netlify, Cloudflare Pages, nginx or Apache prefer host redirects from the redirect rules cheat sheet. The migration redirect checker writes those files for you.

How PathIntact monitors an MkDocs site

• Detection: the mkdocs generator meta tag and Material's md- class names (verified 2026-09-17 against the Material for MkDocs site, confidence 1.0). Detected sites use the generic redirect formats in fix suggestions.
• Render mode: auto, effectively static.
• Versions: mike-style version paths are detected as a /{version}/ pattern; links from the latest version into older ones and canonicals that cross versions are reported.
• Sitemap: MkDocs writes sitemap.xml and a gzip copy TODO(verify); PathIntact reads either, reports non-200 entries, noindex entries, drift and orphans.
• Anchors: every #fragment link is compared with the ids on the target page, with closest-match hints when a heading was renamed.

Check my docs