Update docs @link resolution to better handle unstable APIs

Author: brophdawg11

docs/api/data-routers/createBrowserRouter.md

@@ -610,7 +610,7 @@ the `submitting` portion of the navigation for non-`GET` requests.
 ### opts.window
 
 [`Window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) object
-override — defaults to the global `window` instance.
+override. Defaults to the global `window` instance.
 
 ## Returns
 

docs/api/data-routers/createHashRouter.md

@@ -609,7 +609,7 @@ the `submitting` portion of the navigation for non-`GET` requests.
 ### opts.window
 
 [`Window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) object
-override — defaults to the global `window` instance.
+override. Defaults to the global `window` instance.
 
 ## Returns
 

docs/api/declarative-routers/BrowserRouter.md

@@ -44,5 +44,5 @@ Application basename
 ### window
 
 [`Window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) object
-override — defaults to the global `window` instance
+override. Defaults to the global `window` instance
 

docs/api/declarative-routers/HashRouter.md

@@ -45,5 +45,5 @@ Application basename
 ### window
 
 [`Window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) object
-override — defaults to the global `window` instance
+override. Defaults to the global `window` instance
 

docs/api/rsc/RSCStaticRouter.md

@@ -31,7 +31,7 @@ to release notes for relevant changes.</docs-warning>
 [Reference Documentation ↗](https://api.reactrouter.com/v7/functions/react_router.unstable_RSCStaticRouter.html)
 
 Pre-renders an [`unstable_RSCPayload`](https://api.reactrouter.com/v7/types/react_router.unstable_RSCPayload.html) to HTML. Usually used in
-[`unstable_routeRSCServerRequest`](https://api.reactrouter.com/v7/functions/react_router.unstable_routeRSCServerRequest.html)'s `renderHTML` callback.
+[`unstable_routeRSCServerRequest`](../rsc/routeRSCServerRequest)'s `renderHTML` callback.
 
 ```tsx
 import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
@@ -70,5 +70,5 @@ function RSCStaticRouter({ getPayload }: RSCStaticRouterProps)
 ### getPayload
 
 A function that starts decoding of the [`unstable_RSCPayload`](https://api.reactrouter.com/v7/types/react_router.unstable_RSCPayload.html). Usually passed
-through from [`unstable_routeRSCServerRequest`](https://api.reactrouter.com/v7/functions/react_router.unstable_routeRSCServerRequest.html)'s `renderHTML`.
+through from [`unstable_routeRSCServerRequest`](../rsc/routeRSCServerRequest)'s `renderHTML`.
 

docs/api/rsc/routeRSCServerRequest.md

@@ -98,7 +98,7 @@ Whether to hydrate the server response with the RSC payload. Defaults to `true`.
 
 ### opts.renderHTML
 
-A function that renders the [`unstable_RSCPayload`](https://api.reactrouter.com/v7/types/react_router.unstable_RSCPayload.html) to HTML, usually using a [`<RSCStaticRouter>`](https://api.reactrouter.com/v7/functions/react_router.unstable_RSCStaticRouter.html).
+A function that renders the [`unstable_RSCPayload`](https://api.reactrouter.com/v7/types/react_router.unstable_RSCPayload.html) to HTML, usually using a [`<RSCStaticRouter>`](../rsc/RSCStaticRouter).
 
 ### opts.request
 

packages/react-router/lib/dom/lib.tsx

@@ -701,7 +701,7 @@ export interface DOMRouterOpts {
   patchRoutesOnNavigation?: PatchRoutesOnNavigationFunction;
   /**
    * [`Window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) object
-   * override — defaults to the global `window` instance.
+   * override. Defaults to the global `window` instance.
    */
   window?: Window;
 }
@@ -860,7 +860,7 @@ export interface BrowserRouterProps {
   children?: React.ReactNode;
   /**
    * [`Window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) object
-   * override — defaults to the global `window` instance
+   * override. Defaults to the global `window` instance
    */
   window?: Window;
 }
@@ -928,7 +928,7 @@ export interface HashRouterProps {
   children?: React.ReactNode;
   /**
    * [`Window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) object
-   * override — defaults to the global `window` instance
+   * override. Defaults to the global `window` instance
    */
   window?: Window;
 }

scripts/docs.ts

@@ -699,20 +699,27 @@ async function getSignature(code: string) {
  * @returns Text with {@link ...} tags replaced by markdown links
  */
 function resolveLinkTags(text: string): string {
-  // Match {@link ApiName} or {@link ApiName description}
+  // Match {@link ApiName} as well as {@link ApiName | description}
   const linkPattern = /\{@link\s+([^}]+)\}/g;
 
   return text.replace(linkPattern, (match, linkContent) => {
-    const parts = linkContent
-      .replace("@link", "")
-      .trim()
-      .split("|")
-      .map((p) => p.trim());
+    // Split on the pipe in case a different link text is specified after.
+    // This is not standard JSDoc syntax but instead something typedoc picks up
+    // from TSDoc. See:
+    //  - https://jsdoc.app/tags-inline-link
+    //  - https://typedoc.org/documents/Tags.__link_.html
+    const parts = linkContent.split("|").map((p) => p.trim());
     const apiName = parts[0];
     const description = parts[1] || `\`${apiName}\``;
 
-    // Look up the API in the lookup tables
-    let href = repoApiLookup.get(apiName) || typedocLookup.get(apiName)?.href;
+    // Find a proper href for the @link
+    let href =
+      // Prefer exact docs for unstable APIs if they exist (they usually shouldn't)
+      repoApiLookup.get(apiName) ||
+      // But normally we don't include the `unstable_` prefix in the filename/URL
+      repoApiLookup.get(apiName.replace(/^unstable_/, "")) ||
+      // Fall through to typedocs if a repo doc doesn't exist
+      typedocLookup.get(apiName)?.href;
 
     if (!href) {
       // If not found, return as plain text with a warning