@docubook/flame 2.0.2 → 2.1.0

package/.docu/node/deploy.ts

@@ -10,11 +10,12 @@
 import { mkdir } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { DIST_DIR, PROJECT_ROOT } from "./paths";
+import { DIST_DIR, PROJECT_ROOT, servedBasePath } from "./paths";
 import {
   DOCKERFILE_BUN,
   DOCKERFILE_MARKER,
   generateDockerfile,
+  buildNginxConf,
   HEADERS_FILE,
   NGINX_CONF,
   DOCKERIGNORE,
@@ -69,7 +70,7 @@ async function writeDockerFiles() {
   }
 
   if (!existsSync(join(dockerDir, "nginx.conf"))) {
-    await Bun.write(join(dockerDir, "nginx.conf"), NGINX_CONF);
+    await Bun.write(join(dockerDir, "nginx.conf"), buildNginxConf(servedBasePath()));
     log.created("📄 Created nginx.conf");
   }
 
@@ -213,7 +214,10 @@ jobs:
         uses: actions/deploy-pages@v4
 `;
 
-if (import.meta.main) {
+// The CLI dynamically imports this entry point, so import.meta.main is false
+// when running `flame deploy` under Bun. The CLI sets FLAME_CLI_ENTRY before
+// importing; direct `bun deploy.ts` still uses Bun's main-module detection.
+if (import.meta.main || process.env.FLAME_CLI_ENTRY === "1") {
   deploy().catch((err) => {
     console.error("Deploy failed:", err);
     process.exit(1);

package/.docu/node/html.shared.ts

@@ -8,6 +8,8 @@
 
 import { escapeHtml } from "./escapeHtml";
 import { cspMeta } from "./security";
+import { rebaseContentPath } from "./utils";
+import { DEFAULT_BASE_PATH } from "./paths";
 
 import type { SeoMeta } from "./seo";
 
@@ -38,6 +40,21 @@ export interface HtmlShellOptions {
   /** Root-absolute asset URLs (`/assets/...`). Required for pages served at
    * arbitrary paths (404 fallback) — relative depth is wrong there. */
   absoluteAssets?: boolean;
+  /**
+   * URL prefix the site is served under (`""` at the deployment root, else
+   * `/prefix` with no trailing slash). Used to re-base author-written content
+   * paths (favicon, og-image) that carry the default `/docs` prefix. Bundle
+   * assets live at the dist root (`/assets/`) and never take the prefix.
+   * Defaults to `/docs` so callers that never pass a prefix keep the
+   * historical output byte-identical.
+   */
+  basePath?: string;
+  /**
+   * Path the host serves the dist root under (`""` at an origin root, `/repo`
+   * for a GitHub Pages project site). Only root-absolute references need it —
+   * relative ones already line up because pages and assets share it.
+   */
+  deployPath?: string;
 }
 
 export function htmlShell(opts: HtmlShellOptions): string {
@@ -56,18 +73,31 @@ export function htmlShell(opts: HtmlShellOptions): string {
     headExtra,
     bodyExtra,
     absoluteAssets = false,
+    basePath = DEFAULT_BASE_PATH,
+    deployPath = "",
   } = opts;
   const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
   const themeStyle = themeCss ? `\n  <style${nonceAttr}>${escapeHtml(themeCss)}</style>` : "";
   const headInjection = headExtra?.length ? `\n  ${headExtra.join("\n  ")}` : "";
   const bodyInjection = bodyExtra?.length ? `\n  ${bodyExtra.join("\n  ")}` : "";
   const depthPrefix = depth === 0 ? "" : "../".repeat(depth);
-  const assetPrefix = absoluteAssets ? "/assets/" : depthPrefix + "assets/";
+  // Bundle assets (JS, CSS, chunks) are written to the dist root and are
+  // independent of the docs prefix; pages climb out of the prefix with `../`.
+  // Depth-independent URLs (404 fallback) still carry the host's deployment
+  // path, which relative climbs cancel out.
+  const assetPrefix = absoluteAssets ? `${deployPath}/assets/` : depthPrefix + "assets/";
   const clientScript = js
     ? `\n  <link rel="modulepreload" href="${escapeHtml(assetPrefix + js)}">\n  <script type="module"${nonceAttr} src="${escapeHtml(assetPrefix + js)}"></script>`
     : "";
-  const resolvePath = (path: string) =>
-    absoluteAssets ? path : path.startsWith("/") ? depthPrefix + path.slice(1) : path;
+  const resolvePath = (path: string) => {
+    if (!path.startsWith("/")) return path;
+    // Author-written content paths (favicon, logo) are root-relative as they
+    // appear on disk, e.g. "/docs/assets/images/favicon.ico". Re-base a leading
+    // default prefix onto the configured one, otherwise the asset 404s at the
+    // old path after a subpath change.
+    const rebased = rebaseContentPath(path, basePath);
+    return absoluteAssets ? `${deployPath}${rebased}` : depthPrefix + rebased.slice(1);
+  };
 
   // Build SEO meta tags (OG, Twitter, canonical)
   let seoTags = "";

package/.docu/node/html.ts

@@ -1,6 +1,8 @@
 import type { HtmlShellOptions } from "./html.shared";
 export type { HtmlShellOptions };
 import { cspMeta } from "./security";
+import { rebaseContentPath } from "./utils";
+import { DEFAULT_BASE_PATH } from "./paths";
 
 export function htmlShell(opts: HtmlShellOptions): string {
   const {
@@ -18,18 +20,31 @@ export function htmlShell(opts: HtmlShellOptions): string {
     headExtra,
     bodyExtra,
     absoluteAssets = false,
+    basePath = DEFAULT_BASE_PATH,
+    deployPath = "",
   } = opts;
   const nonceAttr = nonce ? ` nonce="${Bun.escapeHTML(nonce)}"` : "";
   const themeStyle = themeCss ? `\n  <style${nonceAttr}>${Bun.escapeHTML(themeCss)}</style>` : "";
   const headInjection = headExtra?.length ? `\n  ${headExtra.join("\n  ")}` : "";
   const bodyInjection = bodyExtra?.length ? `\n  ${bodyExtra.join("\n  ")}` : "";
   const depthPrefix = depth === 0 ? "" : "../".repeat(depth);
-  const assetPrefix = absoluteAssets ? "/assets/" : depthPrefix + "assets/";
+  // Bundle assets (JS, CSS, chunks) are written to the dist root and are
+  // independent of the docs prefix; pages climb out of the prefix with `../`.
+  // Depth-independent URLs (404 fallback) still carry the host's deployment
+  // path, which relative climbs cancel out.
+  const assetPrefix = absoluteAssets ? `${deployPath}/assets/` : depthPrefix + "assets/";
   const clientScript = js
     ? `\n  <link rel="modulepreload" href="${Bun.escapeHTML(assetPrefix + js)}">\n  <script type="module"${nonceAttr} src="${Bun.escapeHTML(assetPrefix + js)}"></script>`
     : "";
-  const resolvePath = (path: string) =>
-    absoluteAssets ? path : path.startsWith("/") ? depthPrefix + path.slice(1) : path;
+  const resolvePath = (path: string) => {
+    if (!path.startsWith("/")) return path;
+    // Author-written content paths (favicon, logo) are root-relative as they
+    // appear on disk, e.g. "/docs/assets/images/favicon.ico". Re-base a leading
+    // default prefix onto the configured one, otherwise the asset 404s at the
+    // old path after a subpath change.
+    const rebased = rebaseContentPath(path, basePath);
+    return absoluteAssets ? `${deployPath}${rebased}` : depthPrefix + rebased.slice(1);
+  };
 
   // Build SEO meta tags (OG, Twitter, canonical)
   let seoTags = "";

package/.docu/node/hydrate.node.ts

@@ -14,6 +14,8 @@ import {
   LIB_DIR,
   STYLES_DIR,
   loadDocuConfig,
+  resolveBasePath,
+  servedDeployPath,
 } from "./paths";
 import { buildThemeCss, createMdxModuleEntries, getThemeConfig } from "./hydrate";
 import { atomicWriteFile, computeTailwindCacheKey, readStyleCss } from "./cache-key";
@@ -232,6 +234,10 @@ export async function buildClientBundle(
             `const docuConfig = ${JSON.stringify(resolved)};`,
             `export const routes = docuConfig.routes || [];`,
             `export const config = docuConfig;`,
+            `export const basePath = ${JSON.stringify(resolveBasePath(config))};`,
+            // Dev serves the project from the origin root, so the host's
+            // deployment path only reaches the production bundle.
+            `export const deployPath = ${JSON.stringify(servedDeployPath())};`,
           ].join("\n");
         },
       },

package/.docu/node/hydrate.ts

@@ -3,7 +3,15 @@ import { basename, join } from "node:path";
 import { mkdir, rename, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { resolveTheme, generateThemeCss, presetRegistry } from "@docubook/themes-colors";
-import { ASSETS_DIR, cleanOldBundles, LIB_DIR, STYLES_DIR, loadDocuConfig } from "./paths";
+import {
+  ASSETS_DIR,
+  cleanOldBundles,
+  LIB_DIR,
+  STYLES_DIR,
+  loadDocuConfig,
+  resolveBasePath,
+  servedDeployPath,
+} from "./paths";
 import { atomicWriteFile, computeTailwindCacheKey, readStyleCss } from "./cache-key";
 import { resolveRoutes } from "./fs-scanner";
 import type { AssetManifest, DocuRoute } from "./types";
@@ -161,6 +169,13 @@ export async function buildClientBundle(
                 `const docuConfig = ${JSON.stringify(resolved)};`,
                 `export const routes = docuConfig.routes || [];`,
                 `export const config = docuConfig;`,
+                // The client bundle cannot read docu.json at runtime, so the
+                // resolved prefix is inlined here — same value the server-side
+                // render and the static build use.
+                `export const basePath = ${JSON.stringify(resolveBasePath(config))};`,
+                // Dev serves the project from the origin root, so the host's
+                // deployment path only reaches the production bundle.
+                `export const deployPath = ${JSON.stringify(servedDeployPath())};`,
               ].join("\n"),
               loader: "ts",
             };

package/.docu/node/mdx.ts

@@ -12,23 +12,93 @@ import {
 } from "@docubook/core";
 import { createMdxComponents } from "@docubook/markdown";
 import { getGitLastModified, getGitLastModifiedBatch, getFilesystemMtime } from "./git";
+import { basePath, servedDeployPath } from "./paths";
+import { isDocsPath, rebaseContentPath } from "./base-path";
 
 /**
- * Return the value with `.html` appended, or null if the value should be left
- * unchanged.  Rules:
- *  - Must be a string
- *  - Must start with /docs/  (the /docs root index needs no suffix)
- *  - Must not be an external URL, contain a fragment, or already end in .html
+ * Does an author-written absolute path belong to the docs site?
+ *
+ * At a root deployment the docs own `/`, so every in-site path is a candidate
+ * (the historical rule for authored content); otherwise the shared
+ * {@link isDocsPath} gate applies and sibling app routes stay untouched.
+ */
+function isContentPath(pathname: string, resolvedBasePath: string): boolean {
+  return resolvedBasePath.length === 0 || isDocsPath(pathname, resolvedBasePath);
+}
+
+/** Split an authored value into its pathname and any `?query`/`#fragment`. */
+function splitContentPath(value: string): { pathname: string; suffix: string } {
+  const cut = value.search(/[?#]/);
+  if (cut === -1) return { pathname: value.replace(/\/+$/, "") || "/", suffix: "" };
+  return {
+    pathname: value.slice(0, cut).replace(/\/+$/, "") || "/",
+    suffix: value.slice(cut),
+  };
+}
+
+/**
+ * Resolve an author-written content **link** for the deployment.
+ *
+ * Authors link to sibling pages the way they sit on disk (`/docs/guide/y`). The
+ * static build serves those pages as flat `.html` files, and a non-default
+ * `meta.basePath` — or a host that publishes the dist under a path (a GitHub
+ * Pages project site) — moves the authored segment. Re-base it onto the
+ * configured prefix, add the deployment path, and keep the `.html` suffix on
+ * page links. Returns null when nothing moves, so the default `/docs`
+ * deployment keeps emitting the same HTML.
  */
-function appendHtml(value: unknown): string | null {
+export function resolveContentHref(
+  value: unknown,
+  resolvedBasePath: string = basePath(),
+  deploymentPath: string = servedDeployPath()
+): string | null {
   if (typeof value !== "string") return null;
-  if (/^https?:\/\//.test(value)) return null;
-  if (!value.startsWith("/docs/")) return null;
-  if (value.includes("#")) return null;
-  if (value.endsWith(".html")) return null;
-  return `${value}.html`;
+  if (/^[a-z][a-z\d+.-]*:|^\/\//i.test(value)) return null; // external / protocol-relative
+  if (!value.startsWith("/") || value === "/") return null;
+
+  const { pathname, suffix } = splitContentPath(value);
+  if (!isContentPath(pathname, resolvedBasePath)) return null;
+
+  const rebased = rebaseContentPath(pathname, resolvedBasePath);
+  // The docs root is a directory index, fragments keep the authored
+  // extensionless form (hosts with `try_files` serve the pair), and files keep
+  // their own suffix.
+  const isDirectory =
+    rebased === "/" || rebased === resolvedBasePath || /\.[a-z0-9]+$/i.test(rebased);
+  const target = isDirectory || suffix.includes("#") ? rebased : `${rebased}.html`;
+  const resolved = `${deploymentPath}${target}${suffix}`;
+  return resolved === value ? null : resolved;
 }
 
+/**
+ * Resolve an author-written content **asset** path (`![alt](/docs/assets/x.png)`)
+ * for the deployment. Same re-basing rules as {@link resolveContentHref}, minus
+ * the `.html` suffix — assets are files, not routes.
+ */
+export function resolveContentSrc(
+  value: unknown,
+  resolvedBasePath: string = basePath(),
+  deploymentPath: string = servedDeployPath()
+): string | null {
+  if (typeof value !== "string") return null;
+  if (/^[a-z][a-z\d+.-]*:|^\/\//i.test(value)) return null;
+  if (!value.startsWith("/") || value === "/") return null;
+
+  const { pathname, suffix } = splitContentPath(value);
+  if (!isContentPath(pathname, resolvedBasePath)) return null;
+
+  const resolved = `${deploymentPath}${rebaseContentPath(pathname, resolvedBasePath)}${suffix}`;
+  return resolved === value ? null : resolved;
+}
+
+/** Element → attribute pairs whose author-written values are content assets. */
+const CONTENT_ASSET_ATTRS: Record<string, string> = {
+  img: "src",
+  source: "src",
+  video: "src",
+  audio: "src",
+};
+
 interface HastNode {
   type: string;
   tagName?: string;
@@ -44,20 +114,28 @@ interface MdastNode {
 }
 
 /**
- * Rehype plugin: append `.html` to internal `/docs/` hrefs on HTML `<a>` nodes.
- *
- * This covers standard markdown links: `[text](/docs/page)` → `<a href="…">`.
- * It runs in the HAST (HTML AST) phase, where `<a>` elements are real nodes.
+ * Rehype plugin: point author-written hrefs at the deployed docs paths, and
+ * author-written asset paths at the deployed asset tree.
  *
- * Skips: external URLs, anchor-only links, paths that already end in `.html`,
- * and the `/docs` root index (no trailing slash segment).
+ * Links cover both shapes — plain markdown `[text](/docs/page)` and images and
+ * media (`![alt](/docs/assets/x.png)` → `<img src>`) — which only exist in the
+ * HAST phase. Skips: external URLs, anchors, the root index, and anything the
+ * resolver leaves unchanged.
  */
 function rehypeDocsHtmlLinks() {
   return (tree: HastNode) => {
     function walk(node: HastNode): void {
-      if (node.type === "element" && node.tagName === "a") {
-        const fixed = appendHtml(node.properties?.href);
-        if (fixed) node.properties!.href = fixed;
+      if (node.type === "element" && node.properties) {
+        if (node.tagName === "a") {
+          const fixed = resolveContentHref(node.properties.href);
+          if (fixed) node.properties.href = fixed;
+        } else {
+          const attr = node.tagName ? CONTENT_ASSET_ATTRS[node.tagName] : undefined;
+          if (attr) {
+            const fixed = resolveContentSrc(node.properties[attr]);
+            if (fixed) node.properties[attr] = fixed;
+          }
+        }
       }
       if (node.children) {
         for (const child of node.children) walk(child);
@@ -69,7 +147,7 @@ function rehypeDocsHtmlLinks() {
 }
 
 /**
- * Remark plugin: append `.html` to internal `/docs/` hrefs on MDX JSX nodes.
+ * Remark plugin: append `.html` to internal docs hrefs on MDX JSX nodes.
  *
  * MDX JSX elements (`<Card href="…">`, `<LinkCard href="…">`, etc.) live in
  * the MDAST as `mdxJsxFlowElement` / `mdxJsxTextElement` nodes.  They are
@@ -78,7 +156,8 @@ function rehypeDocsHtmlLinks() {
  * intercepts them at the MDAST phase where their `attributes` array is still
  * accessible and mutable.
  *
- * Skips: same rules as `appendHtml` (external URLs, anchors, already `.html`).
+ * Skips: same rules as `resolveContentHref` (external URLs, anchors, already
+ * resolved paths).
  */
 function remarkMdxJsxDocsHtmlLinks() {
   return (tree: MdastNode) => {
@@ -89,7 +168,7 @@ function remarkMdxJsxDocsHtmlLinks() {
       ) {
         for (const attr of node.attributes) {
           if (attr.type === "mdxJsxAttribute" && attr.name === "href") {
-            const fixed = appendHtml(attr.value);
+            const fixed = resolveContentHref(attr.value);
             if (fixed) attr.value = fixed;
           }
         }

package/.docu/node/paths.ts

@@ -2,6 +2,19 @@ import { resolve, join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { readdir, rm, unlink } from "node:fs/promises";
 import type { DocuConfig } from "./types";
+import { resolveBasePath, resolveDeployPath, validateBasePath } from "./base-path";
+import type { BasePathIssue } from "./base-path";
+
+export {
+  DEFAULT_BASE_PATH,
+  normalizeBasePath,
+  canonicalBasePath,
+  resolveBasePath,
+  resolveDeployPath,
+  docsDepth,
+  validateBasePath,
+} from "./base-path";
+export type { BasePathIssue } from "./base-path";
 
 /**
  * FRAMEWORK_ROOT: Where the package code lives (.docu/components, .docu/pages, .docu/styles, .docu/node)
@@ -84,3 +97,105 @@ export function loadDocuConfig(): DocuConfig {
   _config = JSON.parse(readFileSync(DOCU_CONFIG_PATH, "utf-8"));
   return _config!;
 }
+
+/** Default favicon — resolves against the runtime `meta.basePath`. Lives here
+ *  (not in `./base-path`) because it needs the config-loaded `basePath()`. */
+export function defaultFavicon(): string {
+  return `${basePath()}/assets/images/favicon.ico`;
+}
+
+/**
+ * @deprecated Read the value at call time via {@link defaultFavicon} — this
+ * constant is frozen at import and cannot follow `meta.basePath`.
+ */
+export const DEFAULT_FAVICON = "/docs/assets/images/favicon.ico";
+
+/**
+ * Cached base path for the current project. Callers that already hold a config
+ * may pass it in; otherwise the config singleton is loaded on first use.
+ *
+ * Safe to read eagerly at module scope even though `loadDocuConfig()` is only
+ * invoked inside a build: `PROJECT_ROOT` is resolved at import time, and the
+ * fallback (missing or malformed docu.json) is the `/docs` default, so the
+ * value never depends on call order.
+ */
+export function basePath(): string {
+  let config: DocuConfig | null = null;
+  try {
+    config = loadDocuConfig();
+  } catch {
+    // config absent/unreadable (tests, ad-hoc scripts) — use the default
+  }
+  return resolveBasePath(config);
+}
+
+/** Build-output directory for docs pages, e.g. `.docu/dist/docs` or `dist/` at the root. */
+export function docsOutDir(distDir: string, resolvedBasePath: string = basePath()): string {
+  return resolvedBasePath.length === 0 ? distDir : join(distDir, resolvedBasePath.slice(1));
+}
+
+/** Serve-prefix counterpart of {@link docsOutDir}: `""` at the root, else
+ * `/prefix` with no trailing slash. */
+export function servedBasePath(resolvedBasePath: string = basePath()): string {
+  return resolvedBasePath;
+}
+
+/**
+ * Deployment-root path contributed by the host — `""` when the origin serves
+ * the dist at `/`, `/repo` for a GitHub Pages project site. Root-absolute
+ * references (404 fallback assets, the search index) are built from it.
+ */
+export function deployPath(): string {
+  let config: DocuConfig | null = null;
+  try {
+    config = loadDocuConfig();
+  } catch {
+    // config absent/unreadable (tests, ad-hoc scripts) — assume an origin root
+  }
+  return resolveDeployPath(config);
+}
+
+/**
+ * {@link deployPath} for the current mode: a host path only exists in built
+ * output. Dev serves the project from the origin root, so writing it into dev
+ * HTML (or a dev client bundle) would point at directories the dev server does
+ * not own.
+ */
+export function servedDeployPath(): string {
+  return process.env.NODE_ENV === "production" ? deployPath() : "";
+}
+
+/**
+ * Fail fast on a `meta.basePath` that cannot be honored (a non-string value) and
+ * hand back the normalization warnings for the caller to log — case, whitespace
+ * and unservable characters are normalized by `resolveBasePath`, not rejected.
+ * Called from the build and dev-server entries so the message lands before any
+ * output is written.
+ */
+export function assertValidBasePath(): BasePathIssue[] {
+  let config: DocuConfig | null = null;
+  try {
+    config = loadDocuConfig();
+  } catch {
+    return [];
+  }
+
+  const issues = validateBasePath(config?.meta?.basePath);
+  const errors = issues.filter((issue) => issue.level === "error");
+  if (errors.length > 0) {
+    throw new Error(
+      [
+        `Invalid "meta.basePath" in ${DOCU_CONFIG_PATH}:`,
+        ...errors.map((issue) => `  • ${issue.message}`),
+      ].join("\n")
+    );
+  }
+  return issues.filter((issue) => issue.level === "warning");
+}
+
+/**
+ * Build-output directory for docs pages — derived from `meta.basePath`.
+ * Declared after the resolver above: `const` bindings initialize in order, and
+ * `DOCS_OUT_DIR` reads `DEFAULT_BASE_PATH` through the chain.
+ */
+export const DOCS_OUT_DIR = docsOutDir(DIST_DIR);

package/.docu/node/preview.impl.ts

@@ -9,7 +9,7 @@ import { resolve } from "node:path";
 import type { RuntimeAdapter, ServerHandle } from "./runtime";
 import { logger } from "./logger";
 import { DIST_DIR } from "./paths";
-import { getContentType } from "./utils";
+import { getContentType } from "./server-utils";
 import { SECURITY_HEADERS, generateNonce, cspHeader, injectNonce } from "./security";
 
 function resolveFile(pathname: string): string | null {

package/.docu/node/preview.ts

@@ -2,7 +2,7 @@ import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { logger } from "./logger";
 import { DIST_DIR } from "./paths";
-import { getContentType } from "./utils";
+import { getContentType } from "./server-utils";
 import { SECURITY_HEADERS, generateNonce, cspHeader, injectNonce } from "./security";
 
 const PORT = process.env.PORT || "4173";

package/.docu/node/search-indexer.ts

@@ -16,8 +16,9 @@ import { resolve, join } from "node:path";
 import { getPageContent } from "./mdx";
 import { extractFrontmatterWithContent } from "@docubook/core";
 import { frontmatterField } from "./mdx";
-import { DOCS_DIR, ASSETS_DIR, loadDocuConfig } from "./paths";
-import { scanMdxFiles, docsHtmlHref } from "./utils";
+import { DOCS_DIR, ASSETS_DIR, loadDocuConfig, basePath, deployPath } from "./paths";
+import { scanMdxFiles } from "./server-utils";
+import { docsHtmlHref } from "./utils";
 
 const docuConfig = loadDocuConfig();
 
@@ -72,10 +73,26 @@ export function stripJsx(content: string): string {
   return result;
 }
 
+/**
+ * Absolute URL for a search record.
+ *
+ * Records are clicked straight from the search modal, so they must carry both
+ * prefixes: the docs prefix inside the dist and the host's deployment path
+ * (e.g. `/repo` on a GitHub Pages project site), which no relative depth can
+ * express.
+ */
+export function searchRecordUrl(
+  filePath: string,
+  resolvedBasePath: string = basePath(),
+  deploymentPath: string = deployPath()
+): string {
+  return docsHtmlHref(`${deploymentPath}${resolvedBasePath}/${filePath}`);
+}
+
 export function extractRecords(filePath: string, raw: string): SearchRecord[] {
   const { frontmatter, strippedContent: content } = extractFrontmatterWithContent<Frontmatter>(raw);
   const records: SearchRecord[] = [];
-  const url = docsHtmlHref(`/docs/${filePath}`);
+  const url = searchRecordUrl(filePath);
   const lvl0 = getSectionTitle(filePath);
   const lvl1 = frontmatterField(frontmatter, "title") || null;
 

package/.docu/node/seo.ts

@@ -1,5 +1,7 @@
 import type { DocuConfig } from "./types";
 import { frontmatterField } from "./mdx";
+import { resolveBasePath, resolveDeployPath } from "./paths";
+import { rebaseContentPath } from "./utils";
 
 export interface SeoMeta {
   /** Absolute canonical URL */
@@ -13,6 +15,9 @@ export interface SeoMeta {
 /**
  * Build SEO metadata from config and per-page frontmatter.
  * All fields are derived from existing data — no extra config required.
+ *
+ * All paths are prefixed with the configured base path so canonical and OG
+ * URLs stay correct when the site is served under a subpath.
  */
 export function buildSeoMeta(
   config: DocuConfig,
@@ -20,7 +25,8 @@ export function buildSeoMeta(
   slug: string
 ): SeoMeta {
   const baseURL = config.meta?.baseURL?.replace(/\/+$/, "") || "";
-  const url = slug ? `${baseURL}/docs/${slug}` : `${baseURL}/`;
+  const prefix = resolveBasePath(config);
+  const url = slug ? `${baseURL}${prefix}/${slug}` : `${baseURL}/`;
 
   const result: SeoMeta = {
     url,
@@ -30,13 +36,41 @@ export function buildSeoMeta(
   // Per-page image from frontmatter, fallback to global default from config
   const image = frontmatterField(frontmatter, "image") || config.meta?.ogImage;
   if (image) {
-    // Resolve using URL constructor — handles absolute, root-relative, and relative paths
-    try {
-      result.image = new URL(image, image.startsWith("/") ? baseURL : `${baseURL}/docs/`).href;
-    } catch {
-      result.image = image;
-    }
+    result.image = resolveOgImage(image, baseURL, prefix, resolveDeployPath(config));
   }
 
   return result;
 }
+
+/**
+ * Resolve an OG image path to an absolute URL.
+ *
+ * Handles four shapes:
+ *  - absolute (`https://…`) — used verbatim
+ *  - root-relative already carrying the prefix (`/repo/assets/og.png`) — used as is
+ *  - root-relative still carrying the default prefix (`/docs/assets/og.png`) —
+ *    re-based onto `prefix`, so an existing `docu.json` keeps working after the
+ *    site moves to a different subpath
+ *  - bare relative (`og.png`) — resolved against the prefix directory
+ */
+function resolveOgImage(
+  image: string,
+  baseURL: string,
+  prefix: string,
+  deploymentPath: string
+): string {
+  try {
+    if (/^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(image)) return new URL(image).href;
+    // Content assets live under the docs prefix *inside* the deployment root,
+    // which `baseURL` already spells out (schema: "origin plus deployment
+    // root"), so resolve the path relative to it. The deployment path is only
+    // used to spot an author who spelled the host's segment out themselves.
+    const rebased = rebaseContentPath(image.startsWith("/") ? image : `${prefix}/${image}`, prefix);
+    const withinRoot = rebased.startsWith(`${deploymentPath}/`)
+      ? rebased.slice(deploymentPath.length)
+      : rebased;
+    return new URL(withinRoot.replace(/^\/+/, ""), `${baseURL}/`).href;
+  } catch {
+    return image;
+  }
+}