@docubook/flame 2.0.3 → 2.1.1

package/.docu/node/server-routes.ts

@@ -4,8 +4,9 @@ import { readFileSync, statSync } from "node:fs";
 import React, { type ReactNode } from "react";
 import { renderToString } from "react-dom/server";
 import { compileMdx, frontmatterField } from "./mdx";
-import { DEFAULT_FAVICON, getContentType } from "./utils";
-import { DOCS_DIR, DIST_DIR, PAGES_DIR, PROJECT_ROOT } from "./paths";
+import { getContentType } from "./server-utils";
+import { defaultFavicon } from "./paths";
+import { DOCS_DIR, DIST_DIR, PAGES_DIR, PROJECT_ROOT, servedBasePath, docsDepth } from "./paths";
 import { BuildPluginBuilder } from "./plugin-builder";
 import type { PageContext, PageType } from "./plugin";
 import type { AssetEntry, AssetManifest, DocuConfig, TocItem } from "./types";
@@ -34,7 +35,7 @@ async function createHtmlResponse(
   depth = 0
 ): Promise<Response> {
   const nonce = generateNonce();
-  const favicon = state.docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const favicon = state.docuConfig.meta?.favicon || defaultFavicon();
   const assets: AssetEntry = state.assetManifest[pageType];
   const context: PageContext = {
     ...page,
@@ -55,6 +56,10 @@ async function createHtmlResponse(
     headExtra: state.builder?.collectHead(context),
     bodyExtra: state.builder?.collectBody(context),
     depth,
+    basePath: servedBasePath(),
+    // Dev serves the project from the origin root, so the host's deployment
+    // path never applies here — only the static build writes it into HTML.
+    deployPath: "",
     // 404 pages can be requested at arbitrary depths (e.g. a noLink section
     // path typed in the address bar) — relative asset paths would resolve
     // against the wrong directory and break CSS/JS.
@@ -185,8 +190,8 @@ async function renderDocsServerPage(
 
   const body = renderToString(page);
 
-  // Match build.ts depth calculation: slug.split("/").length, fallback to 1 for empty
-  const depth = slug.length || 1;
+  // Same relative climb as the static build — see docsDepth.
+  const depth = docsDepth(slug.join("/"), servedBasePath());
 
   return createHtmlResponse(
     title,
@@ -233,16 +238,33 @@ async function renderPage(
 
 export async function handleDocsIndex(state: ServerState): Promise<Response> {
   const doc = await getDocsForSlug("", state);
-  if (!doc) return renderPage(NotFoundPage, "404 - Not Found", "", 404, state, {}, 1);
-  return renderDocsServerPage(doc, [], "/docs", state);
+  if (!doc)
+    return renderPage(
+      NotFoundPage,
+      "404 - Not Found",
+      "",
+      404,
+      state,
+      {},
+      docsDepth("", servedBasePath())
+    );
+  return renderDocsServerPage(doc, [], servedBasePath() || "/", state);
 }
 
 export async function handleDocsRoute(slug: string[], state: ServerState): Promise<Response> {
   const path = slug.join("/");
   const doc = await getDocsForSlug(path, state);
   if (!doc)
-    return renderPage(NotFoundPage, "404 - Not Found", "", 404, state, {}, slug.length || 1);
-  return renderDocsServerPage(doc, slug, `/docs/${path}`, state);
+    return renderPage(
+      NotFoundPage,
+      "404 - Not Found",
+      "",
+      404,
+      state,
+      {},
+      docsDepth(path, servedBasePath())
+    );
+  return renderDocsServerPage(doc, slug, `${servedBasePath()}/${path}`, state);
 }
 
 export async function handleIndex(state: ServerState): Promise<Response> {
@@ -287,9 +309,10 @@ export function serveStatic(pathname: string): Response | null {
     if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
   }
 
-  if (decoded.startsWith("/docs/assets/")) {
+  const docsAssetsPrefix = `${servedBasePath()}/assets/`;
+  if (decoded.startsWith(docsAssetsPrefix)) {
     const docsAssetsDir = resolve(DOCS_DIR, "assets");
-    const requestedRelative = decoded.slice("/docs/assets/".length);
+    const requestedRelative = decoded.slice(docsAssetsPrefix.length);
     const docsAsset = resolve(docsAssetsDir, requestedRelative);
     const docsAssetsDirWithSep = docsAssetsDir.endsWith("/") ? docsAssetsDir : docsAssetsDir + "/";
     if (docsAsset !== docsAssetsDir && !docsAsset.startsWith(docsAssetsDirWithSep)) return null;

package/.docu/node/server-utils.ts

@@ -0,0 +1,152 @@
+import { existsSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Server-only helpers that touch the filesystem, git, or `node:path`.
+ *
+ * Kept OUT of `./utils` (which is bundled into the browser): Bun's bundler
+ * injects a full `node:path` polyfill into browser builds for any module that
+ * imports it, even when the calls are never reached at runtime. Everything in
+ * this file is imported exclusively by server-side modules (build, dev server,
+ * search indexer) and their tests.
+ */
+
+export interface ScannedMdxFile {
+  path: string;
+  absPath: string;
+  mtime: number;
+}
+
+/**
+ * Scan a directory recursively for MDX/MD files.
+ * Skips "assets" directories, hidden directories (dot-prefixed), and root-level
+ * index.mdx/index.md (the docs root renders separately in build).
+ * Shared between build.ts and search-indexer.ts.
+ */
+export async function scanMdxFiles(dir: string, baseDir = ""): Promise<ScannedMdxFile[]> {
+  const files: ScannedMdxFile[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    const relativePath = baseDir ? `${baseDir}/${entry.name}` : entry.name;
+
+    if (entry.isDirectory()) {
+      if (entry.name === "assets" || entry.name.startsWith(".")) continue;
+      files.push(...(await scanMdxFiles(fullPath, relativePath)));
+    } else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
+      // Root index renders separately (either extension) — scanning it would
+      // produce a duplicate "index" page colliding with dist/docs/index.html.
+      if (!baseDir && (entry.name === "index.mdx" || entry.name === "index.md")) continue;
+      const stats = await stat(fullPath);
+      let path = relativePath.replace(/\.(mdx|md)$/, "");
+
+      if (/\/index$/.test(path)) {
+        path = path.replace(/\/index$/, "");
+      }
+      files.push({ path, absPath: fullPath, mtime: stats.mtimeMs });
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Resolve the docs root index source — docs/index.mdx preferred, docs/index.md
+ * as fallback (mirrors the dev server's getDocsForSlug extension handling).
+ */
+export function resolveDocsIndexSource(docsDir: string): string | undefined {
+  for (const ext of [".mdx", ".md"]) {
+    const candidate = join(docsDir, `index${ext}`);
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/** Get git last modified date for a file */
+export async function getGitLastModified(filePath: string): Promise<string | null> {
+  try {
+    const cleanPath = filePath.replace(/^\//, "");
+    if (
+      !cleanPath ||
+      !/^[a-zA-Z0-9\-_/.\s]+$/.test(cleanPath) ||
+      /(^|\/)\.\.($|\/)/.test(cleanPath)
+    )
+      return null;
+    const proc = Bun.spawn(["git", "log", "-1", "--format=%cI", "--", cleanPath], {
+      stderr: "ignore",
+    });
+    const text = await new Response(proc.stdout).text();
+    const date = text.trim();
+    return date || null;
+  } catch (err) {
+    console.error("Failed to get git last modified for", filePath, err);
+    return null;
+  }
+}
+
+/** Batch git last modified dates for multiple files in a single spawn */
+export async function getGitLastModifiedBatch(filePaths: string[]): Promise<Map<string, string>> {
+  const result = new Map<string, string>();
+  if (filePaths.length === 0) return result;
+
+  // Filter and validate paths — same guard as getGitLastModified
+  const safePaths: string[] = [];
+  for (const fp of filePaths) {
+    const cleanPath = fp.replace(/^\//, "");
+    if (
+      !cleanPath ||
+      !/^[a-zA-Z0-9\-_/.\s]+$/.test(cleanPath) ||
+      /(^|\/)\.\.($|\/)/.test(cleanPath)
+    ) {
+      console.warn(`[server-utils] getGitLastModifiedBatch: skipping invalid path "${fp}"`);
+      continue;
+    }
+    safePaths.push(cleanPath);
+  }
+
+  if (safePaths.length === 0) return result;
+
+  try {
+    const proc = Bun.spawn(
+      ["git", "log", "--format=%cI", "--name-only", "--diff-filter=ACMR", ...safePaths],
+      { stderr: "ignore" }
+    );
+    const text = await new Response(proc.stdout).text();
+    let currentDate = "";
+
+    for (const line of text.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      if (/^\d{4}-\d{2}-\d{2}T/.test(trimmed)) {
+        currentDate = trimmed;
+      } else if (currentDate && !result.has(trimmed)) {
+        result.set(trimmed, currentDate);
+      }
+    }
+  } catch (err) {
+    console.error("Failed to get git last modified batch for", filePaths, err);
+  }
+
+  return result;
+}
+
+const MIME_TYPES: Record<string, string> = {
+  html: "text/html",
+  css: "text/css",
+  js: "application/javascript",
+  json: "application/json",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  svg: "image/svg+xml",
+  ico: "image/x-icon",
+  woff: "font/woff",
+  woff2: "font/woff2",
+};
+
+export function getContentType(pathname: string): string {
+  const ext = pathname.split(".").pop()?.toLowerCase();
+  return MIME_TYPES[ext || ""] || "application/octet-stream";
+}

package/.docu/node/server.impl.ts

@@ -9,7 +9,7 @@ import { watch, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { createRequire } from "node:module";
 import type { RuntimeAdapter, ServerHandle } from "./runtime";
-import { DOCS_DIR, loadDocuConfig } from "./paths";
+import { DOCS_DIR, loadDocuConfig, resolveBasePath, assertValidBasePath } from "./paths";
 import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
 import { buildClientBundle, computeInlineThemeCss } from "./hydrate.node";
@@ -26,10 +26,15 @@ import {
   type ServerState,
 } from "./server-routes";
 import { wrapPluginResponse } from "./security";
-import { stripDocsHtmlSuffix } from "./utils";
+import { matchDocsSlug, stripDocsHtmlSuffix } from "./utils";
 
 export async function runServer(adapter: RuntimeAdapter): Promise<ServerHandle> {
   const docuConfig = loadDocuConfig();
+  const resolvedBasePath = resolveBasePath(docuConfig);
+
+  // Report normalized prefixes (and stop on a value that cannot be honored)
+  // before the server announces a site that would be built somewhere else.
+  for (const warning of assertValidBasePath()) logger.warn(warning.message);
 
   const parsedPort = parseInt(process.env.PORT ?? "3000", 10);
   const PORT =
@@ -149,7 +154,7 @@ export async function runServer(adapter: RuntimeAdapter): Promise<ServerHandle>
     const url = new URL(req.url);
     // Generated links carry `.html` (matching the static build output);
     // route them to the same handler as their extensionless form.
-    const pathname = stripDocsHtmlSuffix(url.pathname);
+    const pathname = stripDocsHtmlSuffix(url.pathname, resolvedBasePath);
     const startTime = performance.now();
 
     if (builder) {
@@ -197,18 +202,23 @@ export async function runServer(adapter: RuntimeAdapter): Promise<ServerHandle>
 
       let response: Response;
 
-      // Manual route matching — same routes Bun.FileSystemRouter derives
-      // from `.docu/pages/` ("/", "/docs/[[...slug]]", "/404").
+      // The landing page owns `/` in every deployment. At the deployment root
+      // (`meta.basePath: ""`) docs would otherwise claim it, but the build
+      // skips the docs index there — so dev must not serve it either.
+      // Static assets were already handled above, so a root deployment may
+      // still match every other path as a docs route.
       if (pathname === "/") {
         response = await handleIndex(state);
-      } else if (pathname === "/docs" || pathname === "/docs/") {
-        response = await handleDocsIndex(state);
-      } else if (pathname.startsWith("/docs/")) {
-        const slug = pathname.slice("/docs/".length).split("/").filter(Boolean);
-        response =
-          slug.length === 0 ? await handleDocsIndex(state) : await handleDocsRoute(slug, state);
       } else {
-        response = await handleNotFound(state);
+        const docsSlug = matchDocsSlug(pathname, resolvedBasePath);
+        if (docsSlug) {
+          response =
+            docsSlug.length === 0
+              ? await handleDocsIndex(state)
+              : await handleDocsRoute(docsSlug, state);
+        } else {
+          response = await handleNotFound(state);
+        }
       }
 
       logger.request(

package/.docu/node/server.ts

@@ -1,7 +1,7 @@
 import { watch, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { createRequire } from "node:module";
-import { DOCS_DIR, PAGES_DIR, loadDocuConfig } from "./paths";
+import { DOCS_DIR, loadDocuConfig, resolveBasePath, assertValidBasePath } from "./paths";
 import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
 import { buildClientBundle, computeInlineThemeCss } from "./hydrate";
@@ -18,9 +18,14 @@ import {
   type ServerState,
 } from "./server-routes";
 import { wrapPluginResponse } from "./security";
-import { stripDocsHtmlSuffix } from "./utils";
+import { matchDocsSlug, stripDocsHtmlSuffix } from "./utils";
 
 const docuConfig = loadDocuConfig();
+const resolvedBasePath = resolveBasePath(docuConfig);
+
+// Report normalized prefixes (and stop on a value that cannot be honored)
+// before the server announces a site that would be built somewhere else.
+for (const warning of assertValidBasePath()) logger.warn(warning.message);
 
 const parsedPort = parseInt(process.env.PORT ?? "3000", 10);
 const PORT =
@@ -64,16 +69,6 @@ const state: ServerState = {
   builder,
 };
 
-let router: InstanceType<typeof Bun.FileSystemRouter> | null = null;
-try {
-  router = new Bun.FileSystemRouter({
-    style: "nextjs",
-    dir: PAGES_DIR,
-  });
-} catch (e) {
-  logger.warn(`FileSystemRouter failed: ${e instanceof Error ? e.message : String(e)}`);
-}
-
 const hmrClients = new Set<ReadableStreamDefaultController>();
 
 const require = createRequire(import.meta.url);
@@ -151,7 +146,7 @@ const server = Bun.serve({
     const url = new URL(req.url);
     // Generated links carry `.html` (matching the static build output);
     // route them to the same handler as their extensionless form.
-    const pathname = stripDocsHtmlSuffix(url.pathname);
+    const pathname = stripDocsHtmlSuffix(url.pathname, resolvedBasePath);
     const startTime = performance.now();
 
     if (builder) {
@@ -199,24 +194,25 @@ const server = Bun.serve({
         if (staticRes) return staticRes;
       }
 
-      const match = router?.match(pathname);
       let response: Response;
 
-      const routeName = match?.name;
-
-      if (routeName === "/docs/[[...slug]]") {
-        const slugParam = match?.params?.slug;
-        const slug = slugParam ? slugParam.split("/") : [];
-
-        if (slug.length === 0) {
-          response = await handleDocsIndex(state);
-        } else {
-          response = await handleDocsRoute(slug, state);
-        }
-      } else if (routeName === "/") {
+      // The landing page owns `/` in every deployment. At the deployment root
+      // (`meta.basePath: ""`) docs would otherwise claim it, but the build
+      // skips the docs index there — so dev must not serve it either.
+      // Static assets were already handled above, so a root deployment may
+      // still match every other path as a docs route.
+      if (pathname === "/") {
         response = await handleIndex(state);
       } else {
-        response = await handleNotFound(state);
+        const docsSlug = matchDocsSlug(pathname, resolvedBasePath);
+        if (docsSlug) {
+          response =
+            docsSlug.length === 0
+              ? await handleDocsIndex(state)
+              : await handleDocsRoute(docsSlug, state);
+        } else {
+          response = await handleNotFound(state);
+        }
       }
 
       logger.request(

package/.docu/node/types.ts

@@ -18,7 +18,15 @@ export interface DocuRoute {
 export interface DocuMeta {
   title: string;
   description: string;
+  /** Origin + deployment root, e.g. `https://docubook.pro` or `https://user.github.io`. */
   baseURL: string;
+  /**
+   * URL prefix the docs site is served under, e.g. "/docs" (default) or
+   * "/repo" for a GitHub Pages project site. An empty string serves the site
+   * from the deployment root. Set it independently of `baseURL`: the prefix is
+   * appended to `baseURL` when building canonical/OG URLs.
+   */
+  basePath?: string;
   favicon?: string;
   /** Default OG image path (e.g. /docs/assets/images/og.png). Used when page frontmatter has no image. */
   ogImage?: string;
@@ -114,6 +122,11 @@ export interface BuildCacheEntry {
 export interface BuildCacheMeta extends BuildCacheEntry {
   version: number;
   runtime: string;
+  /**
+   * Fingerprint of the framework's rendering sources. Optional so a cache file
+   * written before this field existed is treated as a mismatch and discarded.
+   */
+  render?: string;
 }
 
 export interface BuildCache {

package/.docu/node/utils.ts

@@ -1,175 +1,82 @@
 export { cn, parseDate, formatDate, formatDate2 } from "@docubook/core";
+export {
+  withBasePath,
+  assetHref,
+  applyBasePath,
+  rebaseContentPath,
+  stripDocsHtmlSuffix,
+  matchDocsSlug,
+} from "./base-path";
 
-import { existsSync } from "node:fs";
-import { readdir, stat } from "node:fs/promises";
-import { join } from "node:path";
-
-export interface ScannedMdxFile {
-  path: string;
-  absPath: string;
-  mtime: number;
-}
+import { DEFAULT_BASE_PATH, isDocsPath, rebaseContentPath } from "./base-path";
 
 /**
- * Scan a directory recursively for MDX/MD files.
- * Skips "assets" directories, hidden directories (dot-prefixed), and root-level
- * index.mdx/index.md (the docs root renders separately in build).
- * Shared between build.ts and search-indexer.ts.
+ * Client-safe utilities shared by SSR and the browser bundle.
+ *
+ * This module MUST NOT import Node built-ins (`node:fs`, `node:path`, ...):
+ * Bun's bundler injects a `node:path` polyfill into browser builds for any
+ * bundled module that imports it. Filesystem/git helpers live in
+ * `./server-utils` (server-only).
  */
-export async function scanMdxFiles(dir: string, baseDir = ""): Promise<ScannedMdxFile[]> {
-  const files: ScannedMdxFile[] = [];
-  const entries = await readdir(dir, { withFileTypes: true });
-
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    const relativePath = baseDir ? `${baseDir}/${entry.name}` : entry.name;
-
-    if (entry.isDirectory()) {
-      if (entry.name === "assets" || entry.name.startsWith(".")) continue;
-      files.push(...(await scanMdxFiles(fullPath, relativePath)));
-    } else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
-      // Root index renders separately (either extension) — scanning it would
-      // produce a duplicate "index" page colliding with dist/docs/index.html.
-      if (!baseDir && (entry.name === "index.mdx" || entry.name === "index.md")) continue;
-      const stats = await stat(fullPath);
-      let path = relativePath.replace(/\.(mdx|md)$/, "");
-
-      if (/\/index$/.test(path)) {
-        path = path.replace(/\/index$/, "");
-      }
-      files.push({ path, absPath: fullPath, mtime: stats.mtimeMs });
-    }
-  }
-
-  return files;
-}
 
 export function isExternalUrl(url: string): boolean {
   return /^(https?:\/\/|\/\/)/.test(url);
 }
 
-/**
- * Resolve the docs root index source — docs/index.mdx preferred, docs/index.md
- * as fallback (mirrors the dev server's getDocsForSlug extension handling).
- */
-export function resolveDocsIndexSource(docsDir: string): string | undefined {
-  for (const ext of [".mdx", ".md"]) {
-    const candidate = join(docsDir, `index${ext}`);
-    if (existsSync(candidate)) return candidate;
-  }
-  return undefined;
-}
-
-/** Default favicon — resolves in both build output (`docs/assets/` is copied
- *  to `dist/docs/assets/`) and dev (served from `docs/assets/` via fallback). */
-export const DEFAULT_FAVICON = "/docs/assets/images/favicon.ico";
-
 /** Suffix an internal docs link with `.html` to match the flat static build output. */
 export function docsHtmlHref(path: string): string {
   return `${path}.html`;
 }
 
-/** Map a `/docs{.html,/*.html}` request back to its extensionless route (dev server).
- *  Handles both `/docs/*.html` (pages) and `/docs.html` (edge case). */
-export function stripDocsHtmlSuffix(pathname: string): string {
-  if (pathname === "/docs.html") return "/docs";
-  if (pathname.startsWith("/docs/") && pathname.endsWith(".html"))
-    return pathname.slice(0, -".html".length);
-  return pathname;
-}
+/**
+ * Resolve an authored nav/menu link for the current deployment.
+ *
+ * Docs pages ship as flat `.html` files, so `/docs/guide/routing` has to request
+ * `/docs/guide/routing.html`, while the docs root itself stays a directory index
+ * and keeps no suffix. Authored `/docs/...` paths are re-based onto the
+ * configured prefix, so one `docu.json` keeps working at a custom subpath
+ * (`/repo`) or at a root deployment (`""`). External URLs, hash targets and
+ * paths that already name a file pass through untouched.
+ */
+export function docsNavHref(link: string, resolvedBasePath: string = DEFAULT_BASE_PATH): string {
+  if (isExternalUrl(link) || !link.startsWith("/")) return link;
 
-export function getPath(url: string): string {
-  try {
-    return new URL(url).pathname;
-  } catch (err) {
-    console.error("Failed to parse URL", url, err);
-    return url;
-  }
-}
+  const cut = link.search(/[?#]/);
+  const suffix = cut === -1 ? "" : link.slice(cut);
+  const pathname = (cut === -1 ? link : link.slice(0, cut)).replace(/\/+$/, "") || "/";
 
-/** Get git last modified date for a file */
-export async function getGitLastModified(filePath: string): Promise<string | null> {
-  try {
-    const cleanPath = filePath.replace(/^\//, "");
-    if (
-      !cleanPath ||
-      !/^[a-zA-Z0-9\-_/.\s]+$/.test(cleanPath) ||
-      /(^|\/)\.\.($|\/)/.test(cleanPath)
-    )
-      return null;
-    const proc = Bun.spawn(["git", "log", "-1", "--format=%cI", "--", cleanPath], {
-      stderr: "ignore",
-    });
-    const text = await new Response(proc.stdout).text();
-    const date = text.trim();
-    return date || null;
-  } catch (err) {
-    console.error("Failed to get git last modified for", filePath, err);
-    return null;
-  }
-}
+  // Sibling routes on the same origin are not docs pages — leave them verbatim.
+  if (!isDocsPath(pathname, resolvedBasePath)) return link;
 
-/** Batch git last modified dates for multiple files in a single spawn */
-export async function getGitLastModifiedBatch(filePaths: string[]): Promise<Map<string, string>> {
-  const result = new Map<string, string>();
-  if (filePaths.length === 0) return result;
+  const rebased = rebaseContentPath(pathname, resolvedBasePath);
 
-  // Filter and validate paths — same guard as getGitLastModified
-  const safePaths: string[] = [];
-  for (const fp of filePaths) {
-    const cleanPath = fp.replace(/^\//, "");
-    if (
-      !cleanPath ||
-      !/^[a-zA-Z0-9\-_/.\s]+$/.test(cleanPath) ||
-      /(^|\/)\.\.($|\/)/.test(cleanPath)
-    ) {
-      console.warn(`[utils] getGitLastModifiedBatch: skipping invalid path "${fp}"`);
-      continue;
-    }
-    safePaths.push(cleanPath);
+  // The docs root is a directory index, and anything with an extension is
+  // already a file — neither takes the `.html` suffix.
+  if (rebased === "/" || rebased === resolvedBasePath || /\.[a-z0-9]+$/i.test(rebased)) {
+    return `${rebased}${suffix}`;
   }
+  return `${rebased}.html${suffix}`;
+}
 
-  if (safePaths.length === 0) return result;
+/**
+ * Does `pathname` refer to a link returned by {@link docsNavHref}?
+ *
+ * Nav links reach the browser in two forms: the generated `.html` URL and the
+ * extensionless route a visitor may have typed (the dev server maps both), so
+ * active states have to accept the pair.
+ */
+export function docsNavActive(pathname: string, href: string): boolean {
+  const extensionless = href.endsWith(".html") ? href.slice(0, -".html".length) : href;
+  return (
+    pathname === href || pathname === extensionless || pathname.startsWith(`${extensionless}/`)
+  );
+}
 
+export function getPath(url: string): string {
   try {
-    const proc = Bun.spawn(
-      ["git", "log", "--format=%cI", "--name-only", "--diff-filter=ACMR", ...safePaths],
-      { stderr: "ignore" }
-    );
-    const text = await new Response(proc.stdout).text();
-    let currentDate = "";
-
-    for (const line of text.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      if (/^\d{4}-\d{2}-\d{2}T/.test(trimmed)) {
-        currentDate = trimmed;
-      } else if (currentDate && !result.has(trimmed)) {
-        result.set(trimmed, currentDate);
-      }
-    }
+    return new URL(url).pathname;
   } catch (err) {
-    console.error("Failed to get git last modified batch for", filePaths, err);
+    console.error("Failed to parse URL", url, err);
+    return url;
   }
-
-  return result;
-}
-
-const MIME_TYPES: Record<string, string> = {
-  html: "text/html",
-  css: "text/css",
-  js: "application/javascript",
-  json: "application/json",
-  png: "image/png",
-  jpg: "image/jpeg",
-  jpeg: "image/jpeg",
-  svg: "image/svg+xml",
-  ico: "image/x-icon",
-  woff: "font/woff",
-  woff2: "font/woff2",
-};
-
-export function getContentType(pathname: string): string {
-  const ext = pathname.split(".").pop()?.toLowerCase();
-  return MIME_TYPES[ext || ""] || "application/octet-stream";
 }