fix: add basePath to internal links for GitHub Pages deployment

Internal links (starting with /) were missing the /documents base path
when deployed to GitHub Pages, causing 404 errors.

- Add basePath to marked link renderer for HTML output
- Add basePath to JSDoc {@link} tag processing
- Add rewriteMarkdownLinks() for raw Markdown endpoints

Author: lambdalisue

lib/markdown.ts

@@ -2,6 +2,7 @@
  * Markdown rendering utilities
  */
 import { marked, type Tokens } from "marked";
+import { basePath } from "../data/docs.ts";
 
 /** Generate slug from text (for heading IDs) */
 function slugify(text: string): string {
@@ -13,7 +14,7 @@ function slugify(text: string): string {
     .replace(/\s+/g, "-");
 }
 
-// Configure marked with custom heading renderer for IDs
+// Configure marked with custom heading and link renderers
 marked.use({
   gfm: true, // GitHub Flavored Markdown
   breaks: false,
@@ -26,6 +27,15 @@ marked.use({
         : token.text;
       return `<h${token.depth} id="${id}">${text}</h${token.depth}>\n`;
     },
+    link(token: Tokens.Link): string {
+      // Add basePath to internal links (starting with /)
+      let href = token.href;
+      if (href.startsWith("/") && !href.startsWith("//")) {
+        href = `${basePath}${href}`;
+      }
+      const title = token.title ? ` title="${token.title}"` : "";
+      return `<a href="${href}"${title}>${token.text}</a>`;
+    },
   },
 });
 
@@ -74,14 +84,14 @@ function processJsDocLinks(
 
     // Check if it's a local type in the current package
     if (localTypes?.has(name) && currentPackage) {
-      href = `/api/${currentPackage}#${name.toLowerCase()}`;
+      href = `${basePath}/api/${currentPackage}#${name.toLowerCase()}`;
     } // Check if it's in another package
     else if (typeToPackage?.has(name)) {
       const targetPackage = typeToPackage.get(name)!;
-      href = `/api/${targetPackage}#${name.toLowerCase()}`;
+      href = `${basePath}/api/${targetPackage}#${name.toLowerCase()}`;
     } // Default: link to current package anchor (best effort)
     else if (currentPackage) {
-      href = `/api/${currentPackage}#${name.toLowerCase()}`;
+      href = `${basePath}/api/${currentPackage}#${name.toLowerCase()}`;
     }
 
     // Format the display text
@@ -121,6 +131,21 @@ export function extractTitle(content: string): string | undefined {
   return match?.[1];
 }
 
+/**
+ * Rewrite internal links in markdown content to include basePath.
+ * Transforms [text](/path) to [text](/basePath/path) for internal links.
+ */
+export function rewriteMarkdownLinks(content: string): string {
+  if (!basePath) return content;
+
+  // Match markdown links: [text](url) or [text](url "title")
+  // Only rewrite internal links starting with /
+  return content.replace(
+    /\[([^\]]*)\]\((\/)([^)"'\s]*)((?:\s+"[^"]*")?\))/g,
+    (_, text, _slash, path, rest) => `[${text}](${basePath}/${path}${rest}`,
+  );
+}
+
 /** Extract table of contents from markdown headings (h2 only) */
 export function extractToc(
   content: string,

main.ts

@@ -5,6 +5,7 @@ import { docPages } from "./data/docs.ts";
 import type { PackageDoc } from "./lib/api-docs.ts";
 import { generateApiMarkdown } from "./lib/api-markdown.ts";
 import { generateLlmsTxt } from "./lib/llms.ts";
+import { rewriteMarkdownLinks } from "./lib/markdown.ts";
 import { ApiIndexPage, PackagePage } from "./templates/api/ApiPage.tsx";
 import { MarkdownDocFromFile } from "./templates/docs/MarkdownDoc.tsx";
 import { HomePage } from "./templates/home.tsx";
@@ -41,7 +42,7 @@ app.get("/index.md", async (c) => {
     "",
     content,
   ].join("\n");
-  return c.text(modified, 200, {
+  return c.text(rewriteMarkdownLinks(modified), 200, {
     "Content-Type": "text/markdown; charset=utf-8",
   });
 });
@@ -71,7 +72,7 @@ for (const doc of docPages) {
     : `${doc.path}.md`;
   app.get(mdPath, async (c) => {
     const content = await Deno.readTextFile(doc.file);
-    return c.text(content, 200, {
+    return c.text(rewriteMarkdownLinks(content), 200, {
       "Content-Type": "text/markdown; charset=utf-8",
     });
   });