feat: redirect latest v# to /latest and canonicalize old-version docs

[KevinVandy]

Addresses old-version docs (e.g. Table v8, Query v3/v4) outranking latest docs in search results.

• 308 redirect the latest numbered version (e.g. /query/v5/..., per each library's latestVersion) to /latest/... — both serve identical content from the same branch, so only one URL should be indexed
• Old-version docs pages now emit <link rel="canonical"> (and matching og:url/twitter:url) pointing to their /latest equivalent when the same doc path exists on the latest branch
• Existence check reuses the cached docs path manifest, fetched in parallel with the doc itself; fails open to a self-canonical so a manifest hiccup never breaks the page
• Old versions are never redirected — they stay readable, just no longer compete with latest in search
• Version dropdown collapses "Latest" and the latest numbered version into a single "v# - Latest" option
• The canonical link is emitted by the docs routes' own head() (route head() only sees fresh loaderData for its own match, never for children), and those routes set staticData.ownsCanonicalLink so the root suppresses its default self-canonical — the router doesn't dedupe links, so exactly one tag renders

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	tanstack-com	4dfb207	Commit Preview URL Branch Preview URL	Aug 13 2026, 04:17 PM

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01b9ad8b-873f-4fde-b798-5945bd04ca16

📥 Commits

Reviewing files that changed from the base of the PR and between 4d86ce4 and 4dfb207.

📒 Files selected for processing (5)

• src/components/VersionSelect.tsx
• src/router.tsx
• src/routes/__root.tsx
• src/routes/_library/$libraryId/$version.docs.$.tsx
• src/routes/_library/$libraryId/$version.docs.framework.$framework.$.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

• src/components/VersionSelect.tsx

---

📝 Walkthrough

Walkthrough

The PR standardizes latest-version routing around /latest, detects equivalent documentation paths on the latest branch, redirects numbered latest URLs, and generates route-owned canonical, Open Graph, and Twitter URLs.

Changes

Latest version canonicalization

Layer / File(s)	Summary
Latest version routing src/components/VersionSelect.tsx, src/routes/_library/$libraryId/$version.tsx	The version selector maps the numbered latest version to /latest. Version routes issue permanent 308 redirects while preserving the remaining path.
Latest documentation resolution src/utils/docs-redirects.ts, src/utils/docs.ts, tests/docs-redirects.test.ts	loadDocsRoute checks the latest branch manifest and returns a matching latestDocsPath. Manifest matching covers normalized .md, index.md, missing, and empty paths.
Canonical documentation integration src/router.tsx, src/routes/__root.tsx, src/routes/_library/$libraryId/$version.docs.$.tsx, src/routes/_library/$libraryId/$version.docs.framework.$framework.$.tsx	Documentation routes provide canonical URL overrides for matching latest-version pages and emit matching Open Graph and Twitter URLs. The root route suppresses its canonical link when a matched route owns canonical-link generation.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Mergeability Score: ⚪ Minimal · up to 4dfb2

This change centralizes documentation redirects and canonical URLs to reduce duplicate search indexing while keeping older documentation readable; no actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant Visitor
  participant VersionRoute
  participant DocsRoute
  participant loadDocsRoute
  participant LatestBranchManifest
  Visitor->>VersionRoute: request numbered latest URL
  VersionRoute-->>Visitor: permanent 308 redirect to /latest
  Visitor->>DocsRoute: request versioned document
  DocsRoute->>loadDocsRoute: load document with latest branch
  loadDocsRoute->>LatestBranchManifest: check equivalent docs path
  LatestBranchManifest-->>loadDocsRoute: matching latestDocsPath or null
  loadDocsRoute-->>DocsRoute: document and latestDocsPath
  DocsRoute-->>Visitor: canonical, Open Graph, and Twitter URLs

Loading

Possibly related PRs

• TanStack/tanstack.com#1072: Both PRs modify src/utils/docs.ts and the loadDocsRoute document-loading flow.
• TanStack/tanstack.com#1133: Both PRs modify version routes to permanently redirect version URLs to /latest.

Suggested reviewers: schiller-manuel, tannerlinsley

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the two main changes: redirecting the latest numbered version and canonicalizing old-version documentation pages.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/docs-version-seo-canonicals

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}