Trailing-slash canonicals on all pages + custom trailing-slash sitemap#430
Merged
Conversation
Add a per-page `canonical:` (the page's own www + /docs + trailing-slash URL) to every page in the docs.json navigation. Mintlify normalizes internal links and the auto-generated canonical to no-slash, but the site serves — and Google indexes — the trailing-slash form. Declaring an explicit trailing-slash canonical makes each page self-referential and removes the canonical-to-redirect mismatch Ahrefs flagged. 549 pages here; the other 20 (top pages) already carry it from #422. Generated deterministically from docs.json nav. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mintlify's auto-generated sitemap lists no-slash URLs, which contradicts the trailing-slash canonicals and served URLs. Add a custom sitemap.xml at the repo root (Mintlify serves it in place of the auto-generated one) listing all 569 nav pages with trailing slashes. - scripts/generate-sitemap.mjs regenerates it from docs.json navigation (npm run generate-sitemap), so it's not a stale snapshot. - static-docs-checks CI regenerates and fails the PR if sitemap.xml drifts from docs.json, so it stays in sync. - scripts/** added to .mintignore. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This reverts commit ce22d0b.
This was referenced Jul 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Make every SEO signal agree on the trailing slash
The docs serve and Google indexes the trailing-slash form (
…/foo/), but Mintlify normalizes internal links and the auto-generated canonical/sitemap to no-slash. Rather than fight that (which would mean a URL migration or a marketing-proxy change), this pins the two signals we can control — canonicals and the sitemap — to the trailing-slash form. All three now agree.Note: the internal-link 308s remain (Mintlify strips slashes on render — not fixable in source, confirmed earlier). Those are harmless permanent redirects; this PR removes the canonical mismatch, which is the part that actually affects indexing.
1. Per-page trailing-slash canonical on all 569 pages
docs.jsonnavigation getscanonical: 'https://www.checklyhq.com/docs/<path>/'(self-referential, matches the served URL).canonicalverbatim, trailing slash included.2. Custom
sitemap.xml(trailing slashes)sitemap.xmlat the repo root overrides Mintlify's auto-generated sitemap (supported feature). 569 URLs, all trailing-slash — an exact mirror of the auto-gen URL set (verified 1:1).scripts/generate-sitemap.mjs(npm run generate-sitemap) regenerates it fromdocs.jsonnavigation, so it's not a stale hand-edited file.static-docs-checksregenerates on any docs change and fails the PR ifsitemap.xmldrifts fromdocs.json— so it can't silently go out of sync.lastmodintentionally omitted (optional; including git dates would churn the file — and CI — on every content edit).Verified
mint broken-links: clean.sitemap.xml: valid XML, 569 trailing-slash<loc>, matches Mintlify's URL set exactly.docs.jsonuntouched (the globalseo.metatags.canonicalstays as a no-slash fallback for any future page added without its own canonical).After merge
Spot-check on prod: any page's
<link rel="canonical">ends in/, andwww.checklyhq.com/docs-sitemap.xmlserves the trailing-slash list. Then let Google re-crawl; the Ahrefs canonical/duplicate flags should clear.Follow-up (optional, not in this PR)
New nav pages should get their own
canonical:(else they fall back to the no-slash global). Easy to add a CI check that every nav page declares one — say the word and I'll add it.🤖 Generated with Claude Code