GitBook docs monitoring

GitBook is a hosted editor and publishing platform where page URLs are derived from the page tree and each page's slug. Most breakage comes from editing the tree: moving pages between groups, renaming slugs, and migrating content in or out of GitBook.

How GitBook sites typically break

Moving or renaming pages changes URLs. A page's URL comes from its position and slug. GitBook automatically adds a 307 redirect from the old URL to the new one when a page is moved or renamed, but links from other spaces, from your app and from other sites still deserve a check.

Anchors follow heading text. GitBook generates heading ids from the heading text TODO(verify): slug format; editing a heading breaks fragment links, including the ones GitBook itself created when someone copied a link to a section.

Variants and collections multiply URLs. Content variants (versions) and collections publish parallel trees. Links that hardcode a variant path break when the variant is renamed or retired.

Imported content drags old links along. Importing from Markdown, Confluence or another docs tool keeps the original absolute links, which often point at the old site instead of the new GitBook pages.

External links rot. GitBook does not re-check outbound links after publishing TODO(verify).

What GitBook handles for you, and what it misses

• Editor-side warnings for links to pages that no longer exist inside the same space TODO(verify).
• Automatic 307 redirects when pages are moved or renamed (verified 2026-09-17).
• It misses: external links, links between spaces, anchors targeted from outside, sitemap drift, orphan pages that were unlinked from the tree but still published, soft 404s, and any URL from a platform you migrated away from.

Setting up redirects on GitBook

GitBook supports manual redirects in the site settings (Settings > General > Redirects, choosing temporary 307 or permanent 308) and section-level redirects in .gitbook.yaml for Git-synced spaces (verified 2026-09-17). For Git-synced spaces:

# .gitbook.yaml
redirects:
  old-page: new-page.md
  guides/legacy: guides/current.md

TODO(verify): the exact .gitbook.yaml key and value format (paths vs. file references).

Manual redirects use 307 or 308, never 301. If GitBook sits behind your own CDN or proxy, host-level rules from the redirect rules cheat sheet are an alternative. The migration redirect checker lists every old URL that now 404s and suggests targets.

How PathIntact monitors a GitBook site

• Detection: the GitBook (...) generator meta tag and GitBook asset hosts (verified 2026-09-17 against gitbook.com/docs, confidence 1.0). Fix suggestions use generic redirect formats because GitBook's own format depends on how the space is synced.
• Render mode: auto; published pages are read statically.
• Sitemap: GitBook publishes a sitemap for each site TODO(verify): path. PathIntact follows it, reports non-200 entries and drift, and flags orphans.
• Variants: if variant paths look like versions (for example /v2/), a versioning pattern is detected and links from the latest variant into older ones are reported.
• Anchors: every #fragment link is checked against element ids on the target page, with closest-match suggestions.

Check my docs