Fix legacy docs URL redirects

src/routes/__root.tsx

@@ -1,7 +1,6 @@
 import * as React from 'react'
 import {
   createRootRouteWithContext,
-  redirect,
   useMatches,
   useRouterState,
   HeadContent,
@@ -141,18 +140,7 @@ class OptionalDevtoolsBoundary extends React.Component<
 export const Route = createRootRouteWithContext<{
   queryClient: QueryClient
 }>()({
-  loader: (ctx) => {
-    if (
-      ctx.location.href.match(/\/docs\/(react|vue|angular|svelte|solid)\//gm)
-    ) {
-      throw redirect({
-        href: ctx.location.href.replace(
-          /\/docs\/(react|vue|angular|svelte|solid)\//gm,
-          '/docs/framework/$1/',
-        ),
-      })
-    }
-
+  loader: () => {
     return {
       partnerPlacementSessionSeed: createPartnerPlacementSessionSeed(),
     }

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

@@ -1,7 +1,7 @@
 import { seo } from '~/utils/seo'
 import { ogImageUrl } from '~/utils/og'
 import { Doc } from '~/components/Doc'
-import { loadDocs, resolveDocsRedirect } from '~/utils/docs'
+import { buildDocsRedirectHref, loadDocsRoute } from '~/utils/docs'
 import { findLibrary, getBranch, getLibrary } from '~/libraries'
 import { DocContainer } from '~/components/DocContainer'
 import { getDocsCacheHeaders } from '~/utils/docs-cache-headers'
@@ -10,7 +10,6 @@ import {
   redirect,
   useLocation,
   useMatch,
-  isNotFound,
   createFileRoute,
 } from '@tanstack/react-router'
 
@@ -26,39 +25,34 @@ export const Route = createFileRoute('/_library/$libraryId/$version/docs/$')({
 
     const branch = getBranch(library, version)
     const docsRoot = library.docsRoot || 'docs'
+    const requestedDocsPath = docsPath ?? ''
+    const result = await loadDocsRoute({
+      repo: library.repo,
+      branch,
+      docsRoot,
+      docsPath: requestedDocsPath,
+      defaultDocs: library.defaultDocs ?? 'overview',
+      frameworks: library.frameworks,
+      redirectFromPaths: requestedDocsPath ? [requestedDocsPath] : [],
+    })
 
-    try {
-      return await loadDocs({
-        repo: library.repo,
-        branch,
-        docsRoot,
-        docsPath: docsPath ?? '',
+    if (result.type === 'redirect') {
+      throw redirect({
+        href: buildDocsRedirectHref({
+          baseHref: ctx.location.href,
+          docsPath: result.docsPath,
+          libraryId,
+          version,
+        }),
+        statusCode: 308,
       })
-    } catch (error) {
-      const isNotFoundError =
-        isNotFound(error) ||
-        (error && typeof error === 'object' && 'isNotFound' in error)
-
-      if (isNotFoundError) {
-        const redirectPath = await resolveDocsRedirect({
-          repo: library.repo,
-          branch,
-          docsRoot,
-          docsPaths: docsPath ? [docsPath] : [],
-        })
-
-        if (redirectPath !== null) {
-          throw redirect({
-            href: `/${libraryId}/${version}/docs${redirectPath ? `/${redirectPath}` : ''}`,
-            statusCode: 308,
-          })
-        }
-
-        throw notFound()
-      }
+    }
 
-      throw error
+    if (result.type === 'not-found') {
+      throw notFound()
     }
+
+    return result.doc
   },
   head: ({ loaderData, params }) => {
     const { libraryId, version, _splat: docsPath } = params

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

@@ -1,5 +1,4 @@
 import {
-  isNotFound,
   redirect,
   useLocation,
   useMatch,
@@ -8,7 +7,7 @@ import {
 import { seo } from '~/utils/seo'
 import { ogImageUrl } from '~/utils/og'
 import { Doc } from '~/components/Doc'
-import { loadDocs, resolveDocsRedirect } from '~/utils/docs'
+import { buildDocsRedirectHref, loadDocsRoute } from '~/utils/docs'
 import { getBranch, getLibrary } from '~/libraries'
 import { capitalize } from '~/utils/utils'
 import { DocContainer } from '~/components/DocContainer'
@@ -24,46 +23,39 @@ export const Route = createFileRoute(
     const library = getLibrary(libraryId)
     const branch = getBranch(library, version)
     const docsRoot = library.docsRoot || 'docs'
+    const requestedDocsPath = `framework/${framework}/${docsPath ?? ''}`
+    const result = await loadDocsRoute({
+      repo: library.repo,
+      branch,
+      docsRoot,
+      docsPath: requestedDocsPath,
+      defaultDocs: library.defaultDocs ?? 'overview',
+      frameworks: library.frameworks,
+      redirectFromPaths: docsPath
+        ? [requestedDocsPath, `${framework}/${docsPath}`]
+        : [requestedDocsPath],
+    })
 
-    try {
-      return await loadDocs({
-        repo: library.repo,
-        branch,
-        docsRoot,
-        docsPath: `framework/${framework}/${docsPath ?? ''}`,
+    if (result.type === 'redirect') {
+      throw redirect({
+        href: buildDocsRedirectHref({
+          baseHref: ctx.location.href,
+          docsPath: result.docsPath,
+          libraryId,
+          version,
+        }),
+        statusCode: 308,
       })
-    } catch (error) {
-      // If doc not found, redirect to framework docs root instead of showing 404
-      // This handles cases like switching frameworks where the same doc path doesn't exist
-      // Check both isNotFound() and the serialized form from server functions
-      const isNotFoundError =
-        isNotFound(error) ||
-        (error && typeof error === 'object' && 'isNotFound' in error)
-
-      if (isNotFoundError) {
-        const redirectPath = await resolveDocsRedirect({
-          repo: library.repo,
-          branch,
-          docsRoot,
-          docsPaths: docsPath
-            ? [`framework/${framework}/${docsPath}`, `${framework}/${docsPath}`]
-            : [],
-        })
-
-        if (redirectPath !== null) {
-          throw redirect({
-            href: `/${libraryId}/${version}/docs${redirectPath ? `/${redirectPath}` : ''}`,
-            statusCode: 308,
-          })
-        }
+    }
 
-        throw redirect({
-          to: '/$libraryId/$version/docs/framework/$framework',
-          params: { libraryId, version, framework },
-        })
-      }
-      throw error
+    if (result.type === 'not-found') {
+      throw redirect({
+        to: '/$libraryId/$version/docs/framework/$framework',
+        params: { libraryId, version, framework },
+      })
     }
+
+    return result.doc
   },
   component: Docs,
   headers: ({ params }) => {

src/routes/_library/$libraryId/$version.docs.framework.$framework.{$}[.]md.tsx

@@ -1,5 +1,5 @@
 import { findLibrary, getBranch } from '~/libraries'
-import { loadDocs } from '~/utils/docs'
+import { buildDocsMarkdownRedirectHref, loadDocsRoute } from '~/utils/docs'
 import { notFound, createFileRoute } from '@tanstack/react-router'
 import { getDocsCacheHeaders } from '~/utils/docs-cache-headers'
 import { getContentDispositionHeader } from '~/utils/http-response'
@@ -36,14 +36,38 @@ export const Route = createFileRoute(
 
         const root = library.docsRoot || 'docs'
         const cacheHeaders = getDocsCacheHeaders({ libraryId, version })
-
-        const doc = await loadDocs({
+        const branch = getBranch(library, version)
+        const requestedDocsPath = `framework/${framework}/${docsPath}`
+        const result = await loadDocsRoute({
           repo: library.repo,
-          branch: getBranch(library, version),
+          branch,
           docsRoot: root,
-          docsPath: `framework/${framework}/${docsPath}`,
+          docsPath: requestedDocsPath,
+          defaultDocs: library.defaultDocs ?? 'overview',
+          frameworks: library.frameworks,
+          redirectFromPaths: docsPath
+            ? [requestedDocsPath, `${framework}/${docsPath}`]
+            : [requestedDocsPath],
         })
 
+        if (result.type === 'redirect') {
+          return Response.redirect(
+            buildDocsMarkdownRedirectHref({
+              requestUrl: request.url,
+              docsPath: result.docsPath,
+              libraryId,
+              version,
+            }),
+            308,
+          )
+        }
+
+        if (result.type === 'not-found') {
+          throw notFound()
+        }
+
+        const doc = result.doc
+
         // Filter framework-specific content using framework from URL path
         const filteredContent = filterFrameworkContent(doc.content, {
           framework,
@@ -52,7 +76,7 @@ export const Route = createFileRoute(
         })
 
         const markdownContent = `# ${doc.title}\n${filteredContent}`
-        const filename = `${docsPath || 'file'}.md`
+        const filename = `${result.docsPath || 'file'}.md`
 
         return new Response(markdownContent, {
           headers: {

src/routes/_library/$libraryId/$version.docs.{$}[.]md.tsx

@@ -1,6 +1,6 @@
 import { createFileRoute, notFound } from '@tanstack/react-router'
 import { findLibrary, getBranch } from '~/libraries'
-import { loadDocs } from '~/utils/docs'
+import { buildDocsMarkdownRedirectHref, loadDocsRoute } from '~/utils/docs'
 import { getDocsCacheHeaders } from '~/utils/docs-cache-headers'
 import { getContentDispositionHeader } from '~/utils/http-response'
 import { filterFrameworkContent } from '~/utils/markdown/filterFrameworkContent'
@@ -32,14 +32,35 @@ export const Route = createFileRoute(
 
         const root = library.docsRoot || 'docs'
         const cacheHeaders = getDocsCacheHeaders({ libraryId, version })
-
-        const doc = await loadDocs({
+        const branch = getBranch(library, version)
+        const result = await loadDocsRoute({
           repo: library.repo,
-          branch: getBranch(library, version),
+          branch,
           docsRoot: root,
           docsPath,
+          defaultDocs: library.defaultDocs ?? 'overview',
+          frameworks: library.frameworks,
+          redirectFromPaths: docsPath ? [docsPath] : [],
         })
 
+        if (result.type === 'redirect') {
+          return Response.redirect(
+            buildDocsMarkdownRedirectHref({
+              requestUrl: request.url,
+              docsPath: result.docsPath,
+              libraryId,
+              version,
+            }),
+            308,
+          )
+        }
+
+        if (result.type === 'not-found') {
+          throw notFound()
+        }
+
+        const doc = result.doc
+
         // Filter framework-specific content only if framework is explicitly specified
         const filteredContent = framework
           ? filterFrameworkContent(doc.content, {
@@ -50,7 +71,7 @@ export const Route = createFileRoute(
           : doc.content
 
         const markdownContent = `# ${doc.title}\n${filteredContent}`
-        const filename = `${docsPath || 'file'}.md`
+        const filename = `${result.docsPath || 'file'}.md`
 
         return new Response(markdownContent, {
           headers: {