@docubook/flame 2.0.3 → 2.1.1

package/.docu/components/Context.tsx

@@ -3,7 +3,7 @@
 import { useState } from "react";
 import { cn, docsHtmlHref } from "../node/utils";
 import { Dropdown, DropdownItem } from "@docubook/ui-react/dropdown";
-import { routes, config as docuConfig } from "../node/client-routes";
+import { routes, config as docuConfig, basePath } from "../node/client-routes";
 import { ChevronsUpDown, Check } from "lucide-react";
 import { renderLucideIcon } from "./Lucide";
 
@@ -21,7 +21,7 @@ function getFirstItemHref(route: { href: string; items?: { href: string }[] }):
 }
 
 function getActiveContextRoute(path: string) {
-  const docPath = path.replace(/^\/docs/, "");
+  const docPath = basePath.length > 0 ? path.replace(new RegExp(`^${basePath}`), "") : path;
   return getContextRoutes().find((route) => docPath.startsWith(route.href));
 }
 
@@ -33,12 +33,13 @@ export function Context({ className }: ContextProps) {
 
   const mode = docuConfig.sidebar?.context || "dropdown";
   if (mode === "separator") return null;
-  const activeRoute = pathname.startsWith("/docs") ? getActiveContextRoute(pathname) : undefined;
+  const isDocsPath = basePath.length === 0 || pathname.startsWith(basePath);
+  const activeRoute = isDocsPath ? getActiveContextRoute(pathname) : undefined;
   const contextRoutes = getContextRoutes();
   const fallbackRoute = routes[0];
   const displayRoute = activeRoute || fallbackRoute;
 
-  if (!mounted || !pathname.startsWith("/docs") || contextRoutes.length === 0) {
+  if (!mounted || !isDocsPath || contextRoutes.length === 0) {
     return null;
   }
 
@@ -68,7 +69,7 @@ export function Context({ className }: ContextProps) {
       {contextRoutes.map((route) => {
         const isActive = activeRoute?.href === route.href;
         const firstItemPath = getFirstItemHref(route);
-        const contextPath = docsHtmlHref(`/docs${firstItemPath}`);
+        const contextPath = docsHtmlHref(`${basePath}${firstItemPath}`);
 
         return (
           <DropdownItem

package/.docu/components/DocsLayout.tsx

@@ -1,8 +1,10 @@
 import React from "react";
-import { loadDocuConfig } from "../node/paths";
+import { loadDocuConfig, resolveBasePath } from "../node/paths";
+import { docsNavHref } from "../node/utils";
 import Menu from "./Menu";
 
 const docuConfig = loadDocuConfig();
+const basePath = resolveBasePath(docuConfig);
 
 interface DocsLayoutProps {
   children?: React.ReactNode;
@@ -10,7 +12,7 @@ interface DocsLayoutProps {
   pathname?: string;
 }
 
-export function DocsLayout({ children, repoUrl, pathname = "/docs" }: DocsLayoutProps) {
+export function DocsLayout({ children, repoUrl, pathname = basePath }: DocsLayoutProps) {
   return React.createElement(
     "div",
     { className: "docs-layout flex flex-col min-h-screen w-full" },
@@ -45,12 +47,13 @@ export function DocsLayout({ children, repoUrl, pathname = "/docs" }: DocsLayout
             { className: "flex items-center gap-6 text-sm font-medium text-base-content/80" },
             ...(docuConfig.navbar?.menu || []).map((item: { title: string; href: string }) => {
               const isExternal = /^https?:\/\//.test(item.href);
-              const isDocsActive = item.href === "/docs";
+              const href = isExternal ? item.href : docsNavHref(item.href, basePath);
+              const isDocsActive = href === basePath;
               return React.createElement(
                 "a",
                 {
                   key: item.title,
-                  href: item.href,
+                  href,
                   className: `flex items-center gap-1 hover:text-base-content transition-colors${isDocsActive ? " text-primary font-semibold" : ""}`,
                   ...(isExternal ? { target: "_blank", rel: "noopener noreferrer" } : {}),
                 },

package/.docu/components/Menu.tsx

@@ -5,7 +5,7 @@ import Sublink, { GroupAccordionProvider } from "./Sublink";
 import SidebarGroupHeader from "./SidebarGroupHeader";
 import type { DocuRoute } from "../node/types";
 import { cn } from "../node/utils";
-import { config as docuConfig } from "../node/client-routes";
+import { config as docuConfig, basePath } from "../node/client-routes";
 
 interface MenuProps {
   onNavigate?: () => void;
@@ -15,8 +15,8 @@ interface MenuProps {
 }
 
 function getCurrentContext(path: string): string | undefined {
-  if (!path.startsWith("/docs")) return undefined;
-  const match = path.match(/^\/docs\/([^/]+)/);
+  if (!path.startsWith(basePath)) return undefined;
+  const match = path.match(new RegExp(`^${basePath}/([^/]+)`));
   return match ? match[1] : undefined;
 }
 
@@ -30,10 +30,11 @@ function getContextRoute(contextPath: string, routeList: DocuRoute[]): DocuRoute
 export default function Menu({ onNavigate, className = "", pathname, routes = [] }: MenuProps) {
   const menuRoutes = routes;
   const [currentPath] = useState(
-    () => pathname || (typeof window !== "undefined" ? window.location.pathname : "/docs")
+    () => pathname || (typeof window !== "undefined" ? window.location.pathname : basePath)
   );
 
-  if (!currentPath.startsWith("/docs")) return null;
+  // Root deployment has no prefix to match against: every path belongs to docs.
+  if (basePath.length > 0 && !currentPath.startsWith(basePath)) return null;
 
   const mode = docuConfig.sidebar?.context || "dropdown";
   const navProps = {
@@ -43,7 +44,7 @@ export default function Menu({ onNavigate, className = "", pathname, routes = []
 
   // Shared nav item with border-left overlap wrapper
   const renderBorderItem = (item: DocuRoute, parentRouteHref: string, key: string) => {
-    const fullHref = `/docs${parentRouteHref}${item.href}`;
+    const fullHref = `${basePath}${parentRouteHref}${item.href}`;
     const isActive = currentPath === fullHref || currentPath === `${fullHref}.html`;
     return (
       <li key={key}>
@@ -59,7 +60,7 @@ export default function Menu({ onNavigate, className = "", pathname, routes = []
               href={item.href}
               level={0}
               onNavigate={onNavigate}
-              parentHref={`/docs${parentRouteHref}`}
+              parentHref={`${basePath}${parentRouteHref}`}
             />
           </div>
         </div>
@@ -106,7 +107,7 @@ export default function Menu({ onNavigate, className = "", pathname, routes = []
   }
 
   // Dropdown mode: render only the active context section
-  const isDocsRoot = currentPath === "/docs" || currentPath === "/docs/";
+  const isDocsRoot = currentPath === basePath || currentPath === `${basePath}/`;
   const currentContext = isDocsRoot
     ? menuRoutes[0]?.href.replace(/^\/+|\/+$/, "")
     : getCurrentContext(currentPath);
@@ -132,7 +133,7 @@ export default function Menu({ onNavigate, className = "", pathname, routes = []
               href={contextRoute.href}
               level={0}
               onNavigate={onNavigate}
-              parentHref="/docs"
+              parentHref={basePath}
             />
           </li>
         </ul>

package/.docu/components/Navbar.tsx

@@ -1,8 +1,8 @@
 import type { ReactNode } from "react";
 import { useState } from "react";
 import Anchor from "./Anchor";
-import { cn } from "../node/utils";
-import { config as docuConfig } from "../node/client-routes";
+import { cn, docsNavActive, docsNavHref, rebaseContentPath } from "../node/utils";
+import { config as docuConfig, basePath } from "../node/client-routes";
 import {
   Navbar as BaseNavbar,
   Logo as BaseLogo,
@@ -27,7 +27,11 @@ interface NavbarProps {
 }
 
 function AppLogo({ logo, logoText }: { logo?: { src?: string; alt?: string }; logoText?: string }) {
-  return <BaseLogo src={logo?.src} alt={logo?.alt} text={logoText} href="/docs" />;
+  // `logo.src` is authored as a root-relative path on disk (e.g.
+  // "/docs/assets/images/docu.svg"); re-base it onto the configured prefix so
+  // the logo keeps resolving after a subpath change.
+  const src = logo?.src ? rebaseContentPath(logo.src, basePath) : undefined;
+  return <BaseLogo src={src} alt={logo?.alt} text={logoText} href={basePath || "/"} />;
 }
 
 function AppNavMenu({ menu, currentPath }: { menu: AppNavMenuItem[]; currentPath?: string }) {
@@ -83,9 +87,11 @@ export function NavMenuLink({ item, isActive }: { item: BaseNavMenuItem; isActiv
 }
 
 export function NavItem({ item }: { item: BaseNavMenuItem }) {
+  const href = docsNavHref(item.href, basePath);
   return (
     <Anchor
-      href={item.href}
+      href={href}
+      activeWhen={(path: string) => docsNavActive(path, href)}
       activeClassName="text-primary font-semibold"
       className="text-sm font-medium"
     >
@@ -123,24 +129,20 @@ export function MobileMenuToggle({
           tabIndex={0}
           className="dropdown-content menu bg-base-200 rounded-box z-[1] mt-2 w-52 p-2 shadow"
         >
-          {menu.map((item) => (
-            <li key={item.title + item.href}>
-              <Anchor
-                href={item.href}
-                activeWhen={
-                  currentPath
-                    ? (path: string) =>
-                        path === item.href ||
-                        path.startsWith(item.href + "/") ||
-                        path.endsWith(item.href + ".html")
-                    : undefined
-                }
-                activeClassName="text-primary font-semibold"
-              >
-                {item.title}
-              </Anchor>
-            </li>
-          ))}
+          {menu.map((item) => {
+            const href = docsNavHref(item.href, basePath);
+            return (
+              <li key={item.title + item.href}>
+                <Anchor
+                  href={href}
+                  activeWhen={currentPath ? (path: string) => docsNavActive(path, href) : undefined}
+                  activeClassName="text-primary font-semibold"
+                >
+                  {item.title}
+                </Anchor>
+              </li>
+            );
+          })}
         </ul>
       </details>
     </div>

package/.docu/components/Pagination.tsx

@@ -3,6 +3,7 @@
 import type { ReactNode } from "react";
 import { getPreviousNext } from "../node/route";
 import { docsHtmlHref } from "../node/utils";
+import { basePath } from "../node/client-routes";
 import { PaginationDocs } from "@docubook/ui-react/pagination";
 
 interface PaginationProps {
@@ -34,7 +35,7 @@ export default function Pagination({
       prev={
         prev
           ? {
-              href: docsHtmlHref(`/docs${prev.href}`),
+              href: docsHtmlHref(`${basePath}${prev.href}`),
               title: prev.title,
               description: prev.description,
             }
@@ -43,7 +44,7 @@ export default function Pagination({
       next={
         next
           ? {
-              href: docsHtmlHref(`/docs${next.href}`),
+              href: docsHtmlHref(`${basePath}${next.href}`),
               title: next.title,
               description: next.description,
             }

package/.docu/components/Search.tsx

@@ -37,6 +37,7 @@ FnKey.configure({
 });
 import { cn } from "../node/utils";
 import { search, type SearchResult } from "../node/search";
+import { deployPath } from "../node/client-routes";
 import type { SearchRecord } from "../node/search-indexer";
 
 interface SearchProps {
@@ -48,7 +49,11 @@ let cmdKRegistered = false;
 
 async function loadIndex(): Promise<SearchRecord[]> {
   if (indexCache) return indexCache;
-  const res = await fetch("/assets/search-index.json");
+  // The search index is generated into the dist-root assets tree — next to the
+  // hash-named bundles, not under the docs prefix. A host that serves the dist
+  // from a subpath (GitHub Pages project site) contributes `meta.baseURL`'s
+  // path, which no relative depth can express.
+  const res = await fetch(`${deployPath}/assets/search-index.json`);
   indexCache = await res.json();
   return indexCache!;
 }

package/.docu/components/Sidebar.tsx

@@ -10,7 +10,7 @@ import {
   FileText,
 } from "lucide-react";
 import { Dropdown } from "@docubook/ui-react/dropdown";
-import { cn } from "../node/utils";
+import { cn, docsNavActive, docsNavHref, rebaseContentPath } from "../node/utils";
 import Anchor from "./Anchor";
 import { Context } from "./Context";
 import Menu from "./Menu";
@@ -18,7 +18,7 @@ import { ThemeToggle } from "./Theme";
 import { GitHubLink } from "./Navbar";
 import Search from "./Search";
 import type { TocItem } from "../node/types";
-import { config as docuConfig, routes } from "../node/client-routes";
+import { config as docuConfig, routes, basePath } from "../node/client-routes";
 
 interface SidebarProps {
   tocs?: TocItem[];
@@ -41,10 +41,10 @@ function DesktopSidebar({ className, repoUrl }: { className?: string; repoUrl?:
     <div className={cn("flex h-full flex-col", className)}>
       {/* Logo */}
       <div className="flex h-14 shrink-0 items-center px-5">
-        <a href="/" className="flex items-center gap-2">
+        <a href={basePath || "/"} className="flex items-center gap-2">
           {docuConfig.navbar?.logo?.src && (
             <img
-              src={docuConfig.navbar.logo.src}
+              src={rebaseContentPath(docuConfig.navbar.logo.src, basePath)}
               alt={docuConfig.navbar.logo.alt || ""}
               className="h-6 w-6"
             />
@@ -154,24 +154,25 @@ export function MobileBar({
               </span>
             }
           >
-            {(docuConfig.navbar?.menu || []).map((item) => (
-              <li
-                key={item.href}
-                role="menuitem"
-                className="text-base-content/80 hover:text-base-content hover:bg-base-200 cursor-pointer"
-              >
-                <Anchor
-                  href={item.href}
-                  activeWhen={(path: string) =>
-                    path === item.href || path.startsWith(item.href + "/")
-                  }
-                  activeClassName="text-primary font-semibold"
-                  className="block rounded px-2 py-2 text-sm"
+            {(docuConfig.navbar?.menu || []).map((item) => {
+              const href = docsNavHref(item.href, basePath);
+              return (
+                <li
+                  key={item.href}
+                  role="menuitem"
+                  className="text-base-content/80 hover:text-base-content hover:bg-base-200 cursor-pointer"
                 >
-                  {item.title}
-                </Anchor>
-              </li>
-            ))}
+                  <Anchor
+                    href={href}
+                    activeWhen={(path: string) => docsNavActive(path, href)}
+                    activeClassName="text-primary font-semibold"
+                    className="block rounded px-2 py-2 text-sm"
+                  >
+                    {item.title}
+                  </Anchor>
+                </li>
+              );
+            })}
           </Dropdown>
 
           <button

package/.docu/components/Sublink.tsx

@@ -13,7 +13,7 @@ import { ChevronDown } from "lucide-react";
 import Anchor from "./Anchor";
 import type { DocuRoute } from "../node/types";
 import { cn, docsHtmlHref } from "../node/utils";
-import { config as docuConfig } from "../node/client-routes";
+import { config as docuConfig, basePath } from "../node/client-routes";
 
 /** Exclusive accordion for level >= 2 sidebar groups — opening one group
  * closes the previously open one. All level >= 2 groups default to closed
@@ -55,9 +55,9 @@ export default function Sublink({
   parentHref = "",
   pathname: pathnameProp,
 }: SublinkProps) {
-  const fullHref = parentHref ? `${parentHref}${href}` : `/docs${href}`;
+  const fullHref = parentHref ? `${parentHref}${href}` : `${basePath}${href}`;
   const currentPathname =
-    pathnameProp || (typeof window !== "undefined" ? window.location.pathname : "/docs");
+    pathnameProp || (typeof window !== "undefined" ? window.location.pathname : basePath);
 
   // Groups with children are exclusive accordions (default closed, expand on
   // click). In separator mode every nav item renders at level 0 (sections are

package/.docu/lib/build.deno.js

@@ -1,4 +1,4 @@
-import { n as runBuildCli } from "./build.impl-BSt6Vikt.js";
+import { n as runBuildCli } from "./build.impl-oTVkE6D9.js";
 //#region .docu/node/build.deno.ts
 await runBuildCli();
 process.exit(0);

package/.docu/lib/build.impl-DxI2YYqL.js

@@ -0,0 +1,2 @@
+import { n as runBuildCli } from "./build.impl-oTVkE6D9.js";
+export { runBuildCli };

package/.docu/lib/{build.impl-BSt6Vikt.js → build.impl-oTVkE6D9.js}

@@ -1,7 +1,7 @@
-import { a as DOCS_DIR, c as PAGES_DIR, f as loadDocuConfig, i as DOCS_ASSETS_DIR, l as PROJECT_ROOT, n as CACHE_FILE, r as DIST_DIR, t as ASSETS_DIR } from "./paths-Cbz-dj4s.js";
-import { C as hashMdxSources, D as loadPlugins, E as BuildPluginBuilder, S as atomicWriteFile, T as runtimeStamp, _ as getPageStripped, a as IndexPage, b as buildClientBundle, c as captureException, d as clearDerivedPageCaches, f as compileMdx, g as getPageFrontmatter, h as getPageContent, i as DocsLayout, l as initSentry, m as frontmatterField, o as NotFoundPage, p as compileMdxModule, r as htmlShell, s as DocsPage, u as generateSearchIndex, v as registerPageContent, w as hookMemoryPressure, x as computeInlineThemeCss, y as getGitLastModifiedBatch } from "./html.shared-CsEFmy_Y.js";
-import { c as scanMdxFiles, d as cspHeader, p as generateNonce, s as resolveDocsIndexSource } from "./utils-B_CoyKie.js";
-import { t as logger } from "./logger-DFKQUy8M.js";
+import { D as resolveDeployPath, E as resolveBasePath, S as docsDepth, T as rebaseContentPath, _ as loadDocuConfig, a as DOCS_DIR, f as assertValidBasePath, g as deployPath, h as defaultFavicon, i as DOCS_ASSETS_DIR, l as PAGES_DIR, n as CACHE_FILE, o as DOCS_OUT_DIR, r as DIST_DIR, t as ASSETS_DIR, u as PROJECT_ROOT, y as servedBasePath } from "./paths-CHXABfXa.js";
+import { C as hashMdxSources, D as BuildPluginBuilder, E as runtimeStamp, O as loadPlugins, S as atomicWriteFile, T as renderToolchainStamp, _ as getPageStripped, a as IndexPage, b as buildClientBundle, c as captureException, d as clearDerivedPageCaches, f as compileMdx, g as getPageFrontmatter, h as getPageContent, i as DocsLayout, l as initSentry, m as frontmatterField, o as NotFoundPage, p as compileMdxModule, r as htmlShell, s as DocsPage, u as generateSearchIndex, v as registerPageContent, w as hookMemoryPressure, x as computeInlineThemeCss, y as getGitLastModifiedBatch } from "./html.shared-RPCM1y5Q.js";
+import { a as cspHeader, n as resolveDocsIndexSource, r as scanMdxFiles, s as generateNonce } from "./server-utils-BYWB7A6T.js";
+import { t as logger } from "./logger-NdMEl8u7.js";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { copyFile, mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
@@ -20,20 +20,41 @@ function isCacheEntry(value) {
 /**
 * 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.
 */
 function buildSeoMeta(config, frontmatter, slug) {
 	const baseURL = config.meta?.baseURL?.replace(/\/+$/, "") || "";
+	const prefix = resolveBasePath(config);
 	const result = {
-		url: slug ? `${baseURL}/docs/${slug}` : `${baseURL}/`,
+		url: slug ? `${baseURL}${prefix}/${slug}` : `${baseURL}/`,
 		siteName: config.meta?.title || ""
 	};
 	const image = frontmatterField(frontmatter, "image") || config.meta?.ogImage;
-	if (image) try {
-		result.image = new URL(image, image.startsWith("/") ? baseURL : `${baseURL}/docs/`).href;
+	if (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, baseURL, prefix, deploymentPath) {
+	try {
+		if (/^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(image)) return new URL(image).href;
+		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 {
-		result.image = image;
+		return image;
 	}
-	return result;
 }
 //#endregion
 //#region .docu/node/build.impl.ts
@@ -60,7 +81,7 @@ async function readCache() {
 			const data = await readFile(CACHE_FILE, "utf-8");
 			const parsed = JSON.parse(data);
 			const meta = parsed.__meta__;
-			if (!meta || meta.version !== 5 || meta.runtime !== runtimeStamp()) return {};
+			if (!meta || meta.version !== 6 || meta.runtime !== runtimeStamp() || meta.render !== renderToolchainStamp()) return {};
 			return parsed;
 		}
 	} catch (err) {
@@ -70,11 +91,12 @@ async function readCache() {
 }
 function stampCache(cache) {
 	cache.__meta__ = {
-		hash: `5:${runtimeStamp()}`,
+		hash: `6:${runtimeStamp()}`,
 		mtime: 0,
 		builtAt: Date.now(),
-		version: 5,
-		runtime: runtimeStamp()
+		version: 6,
+		runtime: runtimeStamp(),
+		render: renderToolchainStamp()
 	};
 }
 async function writeCache(cache) {
@@ -166,8 +188,8 @@ async function renderDocsPage(docuConfig, slug, rawMdx, filePath, gitDates, buil
 	};
 	const headExtra = builder?.collectHead(ctx);
 	const bodyExtra = builder?.collectBody(ctx);
-	const depth = slug ? slug.split("/").length : 1;
-	const favicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+	const depth = docsDepth(slug, servedBasePath());
+	const favicon = docuConfig.meta?.favicon || defaultFavicon();
 	const seo = buildSeoMeta(docuConfig, frontmatter, slug || "");
 	const csp = nonce ? cspHeader(nonce) : void 0;
 	let html = htmlShell({
@@ -182,6 +204,7 @@ async function renderDocsPage(docuConfig, slug, rawMdx, filePath, gitDates, buil
 		nonce,
 		themeCss: inlineThemeCss,
 		depth,
+		basePath: servedBasePath(),
 		headExtra,
 		bodyExtra
 	});
@@ -203,6 +226,7 @@ async function runBuild() {
 	const docuConfig = loadDocuConfig();
 	const args = parseArgs();
 	hookMemoryPressure(clearDerivedPageCaches);
+	for (const warning of assertValidBasePath()) logger.warn(warning.message);
 	logger.buildStart();
 	if (args.clean) {
 		const { rm } = await import("node:fs/promises");
@@ -217,7 +241,7 @@ async function runBuild() {
 	}
 	await mkdir(DIST_DIR, { recursive: true });
 	await mkdir(ASSETS_DIR, { recursive: true });
-	await copyDirectoryRecursive(DOCS_ASSETS_DIR, join(DIST_DIR, "docs", "assets"));
+	await copyDirectoryRecursive(DOCS_ASSETS_DIR, join(DOCS_OUT_DIR, "assets"));
 	const mdxFiles = await scanMdxFiles(DOCS_DIR);
 	const cache = args.force ? {} : await readCache();
 	let built = 0;
@@ -250,6 +274,11 @@ async function runBuild() {
 	});
 	await Promise.all(prePassTasks);
 	const indexSource = resolveDocsIndexSource(DOCS_DIR);
+	const docsIndexPath = join(DOCS_OUT_DIR, "index.html");
+	if (!indexSource && DOCS_OUT_DIR !== DIST_DIR) {
+		const { rm } = await import("node:fs/promises");
+		await rm(docsIndexPath, { force: true });
+	}
 	if (indexSource) try {
 		let indexContent = await readFile(indexSource, "utf-8");
 		if (builder) {
@@ -291,7 +320,7 @@ async function runBuild() {
 	for (const file of mdxFiles) {
 		const rebuildDecision = shouldRebuild(file.path, file.mtime, cache);
 		if (rebuildDecision === "no" && !builder) {
-			const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
+			const outputPath = join(DOCS_OUT_DIR, `${file.path}.html`);
 			if (existsSync(outputPath) && !assetsChanged) {
 				skipped++;
 				continue;
@@ -309,7 +338,7 @@ async function runBuild() {
 			const cached = cache[file.path];
 			if (isCacheEntry(cached) && cached.hash === contentHash) {
 				if (!assetsChanged) {
-					const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
+					const outputPath = join(DOCS_OUT_DIR, `${file.path}.html`);
 					if (existsSync(outputPath)) {
 						cache[file.path] = {
 							...cached,
@@ -329,7 +358,7 @@ async function runBuild() {
 			try {
 				const pageNonce = generateNonce();
 				const html = await renderDocsPage(docuConfig, capturedFile.path, capturedRawMdx, relPath, gitDates, builder, pageNonce);
-				const outputPath = join(DIST_DIR, "docs", `${capturedFile.path}.html`);
+				const outputPath = join(DOCS_OUT_DIR, `${capturedFile.path}.html`);
 				await mkdir(dirname(outputPath), { recursive: true });
 				await writeFile(outputPath, html);
 				cache[capturedFile.path] = {
@@ -348,20 +377,17 @@ async function runBuild() {
 	for (let i = 0; i < buildTasks.length; i += CONCURRENCY) await Promise.all(buildTasks.slice(i, i + CONCURRENCY).map((fn) => fn()));
 	if (indexSource) try {
 		const indexHtml = await renderDocsPage(docuConfig, "", await readFile(indexSource, "utf-8"), indexSource.replace(PROJECT_ROOT + "/", ""), gitDates, builder, generateNonce());
-		await mkdir(join(DIST_DIR, "docs"), { recursive: true });
-		await writeFile(join(DIST_DIR, "docs", "index.html"), indexHtml);
+		if (DOCS_OUT_DIR !== DIST_DIR) {
+			await mkdir(DOCS_OUT_DIR, { recursive: true });
+			await writeFile(docsIndexPath, indexHtml);
+		}
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		errors.push(`index: ${msg}`);
 		console.error(`\n❌ Failed to build index: ${msg}\n`);
 	}
-	else {
-		const msg = "docs root index: docs/index.mdx (or docs/index.md) not found";
-		errors.push(`index: ${msg}`);
-		console.error(`\n❌ Failed to build index: ${msg}\n`);
-	}
 	const landingPage = React.createElement(IndexPage);
-	const landingFavicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+	const landingFavicon = docuConfig.meta?.favicon || defaultFavicon();
 	const landingSeo = buildSeoMeta(docuConfig, docuConfig.meta, "");
 	const landingNonce = generateNonce();
 	const landingContext = {
@@ -383,13 +409,14 @@ async function runBuild() {
 		js: landingContext.assets.js,
 		nonce: landingNonce,
 		themeCss: inlineThemeCss,
+		basePath: servedBasePath(),
 		headExtra: builder?.collectHead(landingContext),
 		bodyExtra: builder?.collectBody(landingContext)
 	});
 	if (builder) landingHtml = await builder.runTransformHtmlChain(landingHtml, landingContext);
 	await writeFile(join(DIST_DIR, "index.html"), landingHtml);
 	const notFoundPage = React.createElement(NotFoundPage);
-	const notFoundFavicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+	const notFoundFavicon = docuConfig.meta?.favicon || defaultFavicon();
 	const notFoundNonce = generateNonce();
 	const notFoundContext = {
 		pageType: "notFound",
@@ -411,7 +438,9 @@ async function runBuild() {
 		js: notFoundContext.assets.js,
 		nonce: notFoundNonce,
 		themeCss: inlineThemeCss,
-		absoluteAssets: true
+		absoluteAssets: true,
+		basePath: servedBasePath(),
+		deployPath: deployPath()
 	});
 	if (builder) notFoundHtml = await builder.runTransformHtmlChain(notFoundHtml, notFoundContext);
 	await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);
@@ -421,7 +450,7 @@ async function runBuild() {
 			slug: f.path,
 			title: f.path.split("/").pop() || f.path,
 			filePath: join(DOCS_DIR, f.path),
-			outputPath: join(DIST_DIR, "docs", `${f.path}.html`)
+			outputPath: join(DOCS_OUT_DIR, `${f.path}.html`)
 		}));
 		await builder.runOnEnd(pages, {
 			assetManifest,
@@ -453,4 +482,4 @@ async function runBuildCli() {
 //#endregion
 export { runBuildCli as n, runBuild as t };
 
-//# sourceMappingURL=build.impl-BSt6Vikt.js.map
+//# sourceMappingURL=build.impl-oTVkE6D9.js.map