From 4853ee5ae0a8ae809e34c1cf46fcc7f95249f650 Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Mon, 15 Jun 2026 09:59:50 -0600
Subject: [PATCH] Fix docs router link freeze

---
 src/components/DocsLayout.tsx            |  5 +++--
 src/components/markdown/MarkdownLink.tsx | 26 +++++++++++++++++++++---
 2 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/src/components/DocsLayout.tsx b/src/components/DocsLayout.tsx
index 5f66bc75f..4b48d6128 100644
--- a/src/components/DocsLayout.tsx
+++ b/src/components/DocsLayout.tsx
@@ -848,6 +848,8 @@ export function DocsLayout({
     })
   }, [groupInitialOpenState])
 
+  const libraryHomePath = `/${libraryId}/${version}`
+
   const menuItems = menuConfig.map((group, i) => {
     const groupKey = `${i}:${String(group.label)}`
 
@@ -919,8 +921,7 @@ export function DocsLayout({
                   </a>
                 ) : isHomeLink ? (
                   <Link
-                    to="/$libraryId/$version"
-                    params={{ libraryId, version }}
+                    to={libraryHomePath}
                     onClick={() => {
                       detailsRef.current.removeAttribute('open')
                     }}
diff --git a/src/components/markdown/MarkdownLink.tsx b/src/components/markdown/MarkdownLink.tsx
index 43942fea3..0ae1996ef 100644
--- a/src/components/markdown/MarkdownLink.tsx
+++ b/src/components/markdown/MarkdownLink.tsx
@@ -29,6 +29,24 @@ function isRoutableInternalLink(link: string) {
   )
 }
 
+function normalizeRoutableInternalPathname(pathname: string) {
+  const routerFrameworkMatch = pathname.match(
+    /^\/router\/([^/]+)\/docs\/framework\/[^/]+\/(.+)$/,
+  )
+
+  if (!routerFrameworkMatch) {
+    return pathname
+  }
+
+  const [, version, docsPath] = routerFrameworkMatch
+
+  if (!version || !docsPath || docsPath.startsWith('examples/')) {
+    return pathname
+  }
+
+  return `/router/${version}/docs/${docsPath}`
+}
+
 export function MarkdownLink({
   href: hrefProp,
   ...rest
@@ -37,14 +55,16 @@ export function MarkdownLink({
 
   if (isRoutableInternalLink(href)) {
     const [hrefWithoutHash, hash] = href.split('#')
-    const hrefWithoutMd = hrefWithoutHash.replace('.md', '')
+    const hrefWithoutMd = normalizeRoutableInternalPathname(
+      hrefWithoutHash.replace('.md', ''),
+    )
 
     return (
       <Link
         {...rest}
         to={hrefWithoutMd}
         hash={hash}
-        preload={undefined}
+        preload={false}
         ref={undefined}
       />
     )
@@ -73,7 +93,7 @@ export function MarkdownLink({
       unsafeRelative="path"
       to={hrefWithoutMd}
       hash={hash}
-      preload={undefined}
+      preload={false}
       ref={undefined}
     />
   )