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

- 308 redirect the latest numbered version (e.g. /query/v5) to /latest,
  since both serve identical content from the same branch
- old-version docs pages emit a rel=canonical to their /latest
  equivalent when the same doc path exists on the latest branch,
  checked via the cached docs path manifest (fails open)
- version dropdown collapses "Latest" and the latest numbered version
  into a single "v# (latest)" option

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: KevinVandy

src/components/VersionSelect.tsx

@@ -13,6 +13,7 @@ export function VersionSelect({ libraryId }: { libraryId: LibraryId }) {
   const library = getLibrary(libraryId)
   const versionConfig = useVersionConfig({
     versions: library.availableVersions,
+    latestVersion: library.latestVersion,
   })
   return (
     <Select
@@ -85,37 +86,38 @@ function useCurrentVersion(versions: string[]) {
   }
 }
 
-function useVersionConfig({ versions }: { versions: string[] }) {
+function useVersionConfig({
+  versions,
+  latestVersion,
+}: {
+  versions: string[]
+  latestVersion: string
+}) {
   const currentVersion = useCurrentVersion(versions)
 
   const versionConfig = React.useMemo(() => {
-    const available = versions.reduce(
-      (acc: SelectOption[], version) => {
-        acc.push({
-          label: version,
-          value: version,
-        })
-        return acc
-      },
-      [
-        {
-          label: 'Latest',
-          value: 'latest',
-        },
-      ],
+    // The latest numbered version and 'latest' are the same docs, so they
+    // collapse into a single option that navigates to the /latest URL.
+    const available = versions.map(
+      (version): SelectOption =>
+        version === latestVersion
+          ? { label: `${version} (latest)`, value: 'latest' }
+          : { label: version, value: version },
     )
 
+    const isLatest =
+      currentVersion.version === latestVersion ||
+      !versions.includes(currentVersion.version)
+
     return {
       label: 'Version',
-      selected: versions.includes(currentVersion.version)
-        ? currentVersion.version
-        : 'latest',
+      selected: isLatest ? 'latest' : currentVersion.version,
       available,
       onSelect: (option: { label: string; value: string }) => {
         currentVersion.setVersion(option.value)
       },
     }
-  }, [currentVersion, versions])
+  }, [currentVersion, versions, latestVersion])
 
   return versionConfig
 }

src/routes/__root.tsx

@@ -75,6 +75,28 @@ type CanonicalHeadMatch = {
   staticData?: {
     includeSearchInCanonical?: boolean
   }
+  loaderData?: unknown
+}
+
+// Loaders can point a page's canonical at a different URL (e.g. old-version
+// docs canonicalize to /latest) by returning `canonicalPathOverride`.
+function getCanonicalPathOverride(
+  matches: ReadonlyArray<CanonicalHeadMatch>,
+): string | null {
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const loaderData = matches[i]?.loaderData
+
+    if (
+      loaderData &&
+      typeof loaderData === 'object' &&
+      'canonicalPathOverride' in loaderData &&
+      typeof loaderData.canonicalPathOverride === 'string'
+    ) {
+      return loaderData.canonicalPathOverride
+    }
+  }
+
+  return null
 }
 
 function getCanonicalHeadTags(matches: ReadonlyArray<CanonicalHeadMatch>): {
@@ -90,7 +112,9 @@ function getCanonicalHeadTags(matches: ReadonlyArray<CanonicalHeadMatch>): {
     includeSearchInCanonical && lastMatch
       ? defaultStringifySearch(lastMatch.search)
       : ''
-  const preferredCanonicalPath = getCanonicalPath(canonicalPath)
+  const preferredCanonicalPath = getCanonicalPath(
+    getCanonicalPathOverride(matches) ?? canonicalPath,
+  )
   const pageUrl = canonicalUrl(
     preferredCanonicalPath ?? canonicalPath,
     canonicalSearch,

src/routes/_library/$libraryId/$version.docs.$.tsx

@@ -1,7 +1,11 @@
 import { seo } from '~/utils/seo'
 import { ogImageUrl } from '~/utils/og'
 import { Doc } from '~/components/Doc'
-import { buildDocsRedirectHref, loadDocsRoute } from '~/utils/docs'
+import {
+  appendPathToDocsHref,
+  buildDocsRedirectHref,
+  loadDocsRoute,
+} from '~/utils/docs'
 import { findLibrary, getBranch, getLibrary } from '~/libraries'
 import { DocContainer } from '~/components/DocContainer'
 import { getDocsCacheHeaders } from '~/utils/docs-cache-headers'
@@ -33,6 +37,7 @@ export const Route = createFileRoute('/_library/$libraryId/$version/docs/$')({
       docsPath: requestedDocsPath,
       defaultDocs: library.defaultDocs ?? 'overview',
       frameworks: library.frameworks,
+      latestBranch: getBranch(library, 'latest'),
       redirectFromPaths: requestedDocsPath ? [requestedDocsPath] : [],
     })
 
@@ -52,7 +57,18 @@ export const Route = createFileRoute('/_library/$libraryId/$version/docs/$')({
       throw notFound()
     }
 
-    return result.doc
+    return {
+      ...result.doc,
+      // Old-version pages that still exist on latest canonicalize to /latest
+      // (read by getCanonicalHeadTags in __root.tsx).
+      canonicalPathOverride: result.latestDocsPath
+        ? appendPathToDocsHref({
+            docsPath: result.latestDocsPath,
+            libraryId,
+            version: 'latest',
+          })
+        : undefined,
+    }
   },
   head: ({ loaderData, params }) => {
     const { libraryId, version, _splat: docsPath } = params

src/routes/_library/$libraryId/$version.docs.framework.$framework.$.tsx

@@ -7,7 +7,11 @@ import {
 import { seo } from '~/utils/seo'
 import { ogImageUrl } from '~/utils/og'
 import { Doc } from '~/components/Doc'
-import { buildDocsRedirectHref, loadDocsRoute } from '~/utils/docs'
+import {
+  appendPathToDocsHref,
+  buildDocsRedirectHref,
+  loadDocsRoute,
+} from '~/utils/docs'
 import { getBranch, getLibrary } from '~/libraries'
 import { capitalize } from '~/utils/utils'
 import { DocContainer } from '~/components/DocContainer'
@@ -31,6 +35,7 @@ export const Route = createFileRoute(
       docsPath: requestedDocsPath,
       defaultDocs: library.defaultDocs ?? 'overview',
       frameworks: library.frameworks,
+      latestBranch: getBranch(library, 'latest'),
       redirectFromPaths: docsPath
         ? [requestedDocsPath, `${framework}/${docsPath}`]
         : [requestedDocsPath],
@@ -55,7 +60,18 @@ export const Route = createFileRoute(
       })
     }
 
-    return result.doc
+    return {
+      ...result.doc,
+      // Old-version pages that still exist on latest canonicalize to /latest
+      // (read by getCanonicalHeadTags in __root.tsx).
+      canonicalPathOverride: result.latestDocsPath
+        ? appendPathToDocsHref({
+            docsPath: result.latestDocsPath,
+            libraryId,
+            version: 'latest',
+          })
+        : undefined,
+    }
   },
   component: Docs,
   headers: ({ params }) => {

src/routes/_library/$libraryId/$version.tsx

@@ -25,6 +25,18 @@ export const Route = createFileRoute('/_library/$libraryId/$version')({
       })
     })
 
+    // The latest numbered version (e.g. /query/v5) serves the exact same
+    // content as /latest; permanently redirect so only one URL gets indexed.
+    if (version === library.latestVersion) {
+      throw redirect({
+        href: ctx.location.href.replace(
+          `/${libraryId}/${version}`,
+          `/${libraryId}/latest`,
+        ),
+        statusCode: 308,
+      })
+    }
+
     library.handleRedirects?.(ctx.location.href)
   },
   loader: async (ctx) => {

src/utils/docs-redirects.ts

@@ -77,6 +77,21 @@ export function resolveDocsPathRedirect({
   return { type: 'not-found' }
 }
 
+export function docsManifestHasPath(
+  manifest: DocsRedirectManifest,
+  docsPath: string,
+) {
+  const normalizedPath = normalizeDocsPath(docsPath)
+
+  if (normalizedPath === null) {
+    return false
+  }
+
+  return manifest.paths.some(
+    (path) => normalizeManifestPath(path) === normalizedPath,
+  )
+}
+
 export function appendPathToDocsHref(opts: {
   docsPath: string
   libraryId: string

src/utils/docs.ts

@@ -8,8 +8,10 @@ import {
   fetchRepoDirectoryContents,
 } from './docs.functions'
 import {
+  appendPathToDocsHref,
   buildDocsMarkdownRedirectHref,
   buildDocsRedirectHref,
+  docsManifestHasPath,
   resolveDocsPathRedirect,
   type DocsPathResolution,
 } from './docs-redirects'
@@ -161,6 +163,7 @@ export type LoadDocsRouteResult =
       type: 'loaded'
       docsPath: string
       doc: Awaited<ReturnType<typeof loadDocs>>
+      latestDocsPath: string | null
     }
   | {
       type: 'redirect'
@@ -176,6 +179,7 @@ export async function loadDocsRoute(opts: {
   docsPath: string
   docsRoot: string
   frameworks: Array<string>
+  latestBranch?: string
   redirectFromPaths: Array<string>
   repo: string
 }): Promise<LoadDocsRouteResult> {
@@ -186,15 +190,21 @@ export async function loadDocsRoute(opts: {
   }
 
   try {
-    return {
-      type: 'loaded',
-      docsPath: resolution.docsPath,
-      doc: await loadDocs({
+    const [doc, latestDocsPath] = await Promise.all([
+      loadDocs({
         repo: opts.repo,
         branch: opts.branch,
         docsRoot: opts.docsRoot,
         docsPath: resolution.docsPath,
       }),
+      findLatestDocsPath(opts, resolution.docsPath),
+    ])
+
+    return {
+      type: 'loaded',
+      docsPath: resolution.docsPath,
+      doc,
+      latestDocsPath,
     }
   } catch (error) {
     if (!isDocsNotFoundError(error)) {
@@ -214,6 +224,39 @@ export async function loadDocsRoute(opts: {
   }
 }
 
+/**
+ * When serving an old version, checks whether the same doc path exists on the
+ * latest branch so the page can canonicalize to its /latest equivalent.
+ * Fails open (null) so a manifest hiccup never breaks the doc itself.
+ */
+async function findLatestDocsPath(
+  opts: {
+    branch: string
+    docsRoot: string
+    latestBranch?: string
+    repo: string
+  },
+  docsPath: string,
+): Promise<string | null> {
+  if (!opts.latestBranch || opts.latestBranch === opts.branch) {
+    return null
+  }
+
+  try {
+    const manifest = await fetchDocsPathManifest({
+      data: {
+        repo: opts.repo,
+        branch: opts.latestBranch,
+        docsRoot: opts.docsRoot,
+      },
+    })
+
+    return docsManifestHasPath(manifest, docsPath) ? docsPath : null
+  } catch {
+    return null
+  }
+}
+
 async function resolveDocsRoutePathWithRedirects(opts: {
   branch: string
   defaultDocs: string
@@ -278,6 +321,7 @@ export async function resolveDocsRedirect(opts: {
 }
 
 export {
+  appendPathToDocsHref,
   buildDocsMarkdownRedirectHref,
   buildDocsRedirectHref,
   fetchFile,

tests/docs-redirects.test.ts

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict'
 import {
   buildDocsMarkdownRedirectHref,
   buildDocsRedirectHref,
+  docsManifestHasPath,
   resolveDocsPathRedirect,
   type DocsRedirectManifest,
 } from '../src/utils/docs-redirects'
@@ -208,4 +209,30 @@ assert.equal(
   'https://tanstack.com/query/v5/docs/framework/react/overview.md?pm=pnpm#motivation',
 )
 
+assert.equal(
+  docsManifestHasPath(
+    manifestWithPaths(['guides/queries.md', 'framework/react/overview.md']),
+    'guides/queries',
+  ),
+  true,
+)
+
+assert.equal(
+  docsManifestHasPath(
+    manifestWithPaths(['guides/queries/index.md']),
+    'guides/queries',
+  ),
+  true,
+)
+
+assert.equal(
+  docsManifestHasPath(
+    manifestWithPaths(['guides/queries.md']),
+    'guides/removed-in-latest',
+  ),
+  false,
+)
+
+assert.equal(docsManifestHasPath(manifestWithPaths(['overview.md']), ''), false)
+
 console.log('docs redirect tests passed')