@farming-labs/theme 0.1.108 → 0.1.109

package/dist/docs-api.d.mts

@@ -34,6 +34,8 @@ interface DocsAPIOptions {
   rootDir?: string;
   /** Docs entry folder (default: read from docs.config) */
   entry?: string;
+  /** Public docs route prefix. Defaults to the docs entry path. */
+  docsPath?: string;
   /** Override the docs content directory when it does not live in app/<entry>. */
   contentDir?: string;
   /** Changelog configuration. */

package/dist/docs-api.mjs

@@ -3,7 +3,7 @@ import { getNextAppDir } from "./get-app-dir.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { buildDocsAskAIContext, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsRobotsResponse, createDocsSitemapResponse, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, formatDocsAskAIPackageHints, getDocsLlmsTxtMaxCharsIssue, getDocsMarkdownCanonicalLinkHeader, getDocsMarkdownVaryHeader, hasDocsMarkdownSignatureAgent, normalizeDocsRelated, performDocsSearch, renderDocsLlmsTxt, renderDocsMarkdownNotFound, renderDocsRelatedMarkdownLines, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsSitemapConfig, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent } from "@farming-labs/docs";
+import { buildDocsAskAIContext, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsRobotsResponse, createDocsSitemapResponse, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, formatDocsAskAIPackageHints, getDocsLlmsTxtMaxCharsIssue, getDocsMarkdownVaryHeader, hasDocsMarkdownSignatureAgent, normalizeDocsRelated, performDocsSearch, renderDocsLlmsTxt, renderDocsMarkdownNotFound, renderDocsRelatedMarkdownLines, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsSitemapConfig, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent } from "@farming-labs/docs";
 import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceConfig, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
@@ -807,7 +807,7 @@ function isHiddenFolderIndexPageDir(dir) {
 		return false;
 	}
 }
-function scanDocsDir(docsDir, entry, locale, excludedDirs = []) {
+function scanDocsDir(docsDir, entry, locale, excludedDirs = [], publicPath = `/${normalizePathSegment(entry) || "docs"}`) {
 	const indexes = [];
 	function isExcluded(dir) {
 		const resolved = path.resolve(dir);
@@ -830,7 +830,7 @@ function scanDocsDir(docsDir, entry, locale, excludedDirs = []) {
 				const rawContent = resolveAgentMdxContent(fileContent, "human");
 				const agentRawContent = resolveAgentMdxContent(fileContent, "agent");
 				const content = stripMdx(rawContent);
-				const url = withLangInUrl(slugParts.length === 0 ? `/${entry}` : `/${entry}/${slugParts.join("/")}`, locale);
+				const url = withLangInUrl(publicDocsRoute(publicPath, slugParts), locale);
 				indexes.push({
 					title,
 					description,
@@ -861,7 +861,7 @@ function scanDocsDir(docsDir, entry, locale, excludedDirs = []) {
 	scan(docsDir, []);
 	return resolveRelatedForSearchPages(indexes);
 }
-function scanChangelogDir(changelogDir, entryPath, changelogPath, locale) {
+function scanChangelogDir(changelogDir, entryPath, changelogPath, locale, publicPath = `/${normalizePathSegment(entryPath) || "docs"}`) {
 	if (!fs.existsSync(changelogDir)) return [];
 	const indexes = [];
 	let entries;
@@ -890,7 +890,7 @@ function scanChangelogDir(changelogDir, entryPath, changelogPath, locale) {
 			const rawContent = resolveAgentMdxContent(fileContent, "human");
 			const agentRawContent = resolveAgentMdxContent(fileContent, "agent");
 			const content = stripMdx(rawContent);
-			const url = withLangInUrl(`/${entryPath}/${changelogPath}/${name}`, locale);
+			const url = withLangInUrl(publicDocsRoute(publicPath, [changelogPath, name]), locale);
 			const tags = Array.isArray(data.tags) ? data.tags.filter((value) => typeof value === "string") : void 0;
 			indexes.push({
 				title,
@@ -935,6 +935,38 @@ function normalizeRequestedMarkdownPath(entry, requestedPath) {
 	const slug = normalizePathSegment(trimmed);
 	return slug ? normalizeUrlPath(`${normalizedEntry}/${slug}`) : normalizedEntry;
 }
+function normalizePublicRequestedMarkdownPath(ctx, requestedPath) {
+	const trimmed = requestedPath.trim().replace(/\.md$/i, "");
+	if (!trimmed) return ctx.publicPath || "/";
+	const normalized = normalizeUrlPath(trimmed.startsWith("/") ? trimmed : `/${trimmed}`);
+	const normalizedEntry = `/${normalizePathSegment(ctx.entryPath)}`;
+	if (normalized === normalizedEntry) return ctx.publicPath || "/";
+	if (normalized.startsWith(`${normalizedEntry}/`)) {
+		const suffix = normalized.slice(normalizedEntry.length + 1);
+		return publicDocsRoute(ctx.publicPath, suffix.split("/").filter(Boolean));
+	}
+	if (ctx.publicPath) {
+		if (normalized === ctx.publicPath || normalized.startsWith(`${ctx.publicPath}/`)) return normalized;
+	} else if (normalized === "/") return "/";
+	const slug = normalizePathSegment(trimmed);
+	return publicDocsRoute(ctx.publicPath, slug ? slug.split("/").filter(Boolean) : []);
+}
+function normalizePublicDocsSlug(ctx, value) {
+	const pathname = normalizeUrlPath(value);
+	const normalizedEntry = `/${normalizePathSegment(ctx.entryPath)}`;
+	if (ctx.publicPath) {
+		if (pathname === ctx.publicPath) return "";
+		if (pathname.startsWith(`${ctx.publicPath}/`)) return normalizePathSegment(pathname.slice(ctx.publicPath.length + 1));
+	} else if (pathname === "/") return "";
+	if (pathname === normalizedEntry) return "";
+	if (pathname.startsWith(`${normalizedEntry}/`)) return normalizePathSegment(pathname.slice(normalizedEntry.length + 1));
+	return normalizePathSegment(pathname);
+}
+function getPublicMarkdownCanonicalLinkHeader({ origin, ctx, requestedPath }) {
+	const canonicalUrl = new URL(normalizePublicRequestedMarkdownPath(ctx, requestedPath), origin);
+	if (ctx.locale) canonicalUrl.searchParams.set("lang", ctx.locale);
+	return `<${canonicalUrl.toString()}>; rel="canonical"`;
+}
 function findDocsMcpPage(entry, pages, requestedPath) {
 	const normalizedRequest = normalizeRequestedMarkdownPath(entry, requestedPath);
 	for (const page of pages) if (normalizeUrlPath(page.url) === normalizedRequest) return page;
@@ -985,6 +1017,95 @@ function resolveMarkdownRequest(entry, url, request) {
 	}
 	return null;
 }
+function normalizeDocsPublicPath(value, entry) {
+	if (typeof value !== "string") return `/${normalizePathSegment(entry)}`;
+	const cleaned = value.trim();
+	if (cleaned === "" || cleaned === "/") return "";
+	return `/${cleaned.replace(/^\/+|\/+$/g, "")}`;
+}
+function publicDocsRoute(publicPath, slugParts = []) {
+	const slug = slugParts.join("/");
+	if (!slug) return publicPath || "/";
+	return publicPath ? `${publicPath}/${slug}` : `/${slug}`;
+}
+function toPublicDocsUrl(value, entry, publicPath) {
+	const normalizedEntry = `/${normalizePathSegment(entry)}`;
+	const hashIndex = value.indexOf("#");
+	const hash = hashIndex >= 0 ? value.slice(hashIndex) : "";
+	const withoutHash = hashIndex >= 0 ? value.slice(0, hashIndex) : value;
+	const queryIndex = withoutHash.indexOf("?");
+	const query = queryIndex >= 0 ? withoutHash.slice(queryIndex) : "";
+	const pathname = normalizeUrlPath(queryIndex >= 0 ? withoutHash.slice(0, queryIndex) : withoutHash);
+	if (publicPath === normalizedEntry) return value;
+	if (pathname === normalizedEntry) return `${publicPath || "/"}${query}${hash}`;
+	if (pathname.startsWith(`${normalizedEntry}/`)) {
+		const suffix = pathname.slice(normalizedEntry.length + 1);
+		return `${publicPath ? `${publicPath}/${suffix}` : `/${suffix}`}${query}${hash}`;
+	}
+	return value;
+}
+function withPublicDocsUrl(page, ctx) {
+	const url = toPublicDocsUrl(page.url, ctx.entryPath, ctx.publicPath);
+	return url === page.url ? page : {
+		...page,
+		url
+	};
+}
+function readDocsPath(root) {
+	for (const ext of FILE_EXTS) {
+		const configPath = path.join(root, `docs.config.${ext}`);
+		if (!fs.existsSync(configPath)) continue;
+		try {
+			const match = fs.readFileSync(configPath, "utf-8").match(/docsPath\s*:\s*["']([^"']*)["']/);
+			if (match) return match[1];
+		} catch {}
+	}
+}
+function resolvePublicMarkdownRequest(entry, docsPath, url, request) {
+	if (docsPath === `/${normalizePathSegment(entry)}`) return null;
+	const pathname = normalizeUrlPath(url.pathname);
+	if (docsPath === "") {
+		if (pathname === `/${normalizePathSegment(entry)}.md`) return {
+			requestedPath: "",
+			delivery: "md_route"
+		};
+		if (pathname !== "/docs.md" && pathname.endsWith(".md")) return {
+			requestedPath: pathname.slice(1, -3),
+			delivery: "md_route"
+		};
+		const hasSignatureAgent = hasDocsMarkdownSignatureAgent(request);
+		if (acceptsMarkdown(request) || hasSignatureAgent) {
+			const delivery = hasSignatureAgent ? "signature_agent" : "accept_header";
+			return {
+				requestedPath: pathname === "/" ? "" : pathname.slice(1),
+				delivery
+			};
+		}
+		return null;
+	}
+	if (pathname === `${docsPath}.md`) return {
+		requestedPath: "",
+		delivery: "md_route"
+	};
+	const slugPrefix = `${docsPath}/`;
+	if (pathname.startsWith(slugPrefix) && pathname.endsWith(".md")) return {
+		requestedPath: pathname.slice(slugPrefix.length, -3),
+		delivery: "md_route"
+	};
+	const hasSignatureAgent = hasDocsMarkdownSignatureAgent(request);
+	if (acceptsMarkdown(request) || hasSignatureAgent) {
+		const delivery = hasSignatureAgent ? "signature_agent" : "accept_header";
+		if (pathname === docsPath) return {
+			requestedPath: "",
+			delivery
+		};
+		if (pathname.startsWith(slugPrefix)) return {
+			requestedPath: pathname.slice(slugPrefix.length),
+			delivery
+		};
+	}
+	return null;
+}
 function renderMarkdownDocument(page, options = {}) {
 	if ("agentRawContent" in page && page.agentRawContent !== void 0) return page.agentRawContent;
 	const relatedLines = renderDocsRelatedMarkdownLines(page.related);
@@ -1771,6 +1892,7 @@ function generateLlmsTxt(indexes, options) {
 function createDocsAPI(options) {
 	const root = options?.rootDir ?? process.cwd();
 	const entry = options?.entry ?? readEntry(root);
+	const docsPath = normalizeDocsPublicPath(options?.docsPath ?? readDocsPath(root), entry);
 	const analytics = options?.analytics;
 	const observability = options?.observability;
 	const appDir = getNextAppDir(root);
@@ -1836,6 +1958,7 @@ function createDocsAPI(options) {
 			const docsDirs = resolveDocsDirCandidates();
 			return {
 				entryPath: entry,
+				publicPath: docsPath,
 				docsDirs,
 				changelogDirs: resolveChangelogDirCandidates(docsDirs)
 			};
@@ -1844,6 +1967,7 @@ function createDocsAPI(options) {
 		const docsDirs = resolveDocsDirCandidates(locale);
 		return {
 			entryPath: entry,
+			publicPath: docsPath,
 			locale,
 			docsDirs,
 			changelogDirs: resolveChangelogDirCandidates(docsDirs)
@@ -1859,13 +1983,13 @@ function createDocsAPI(options) {
 		let next = [];
 		for (const docsDir of ctx.docsDirs) {
 			const excludedDirs = ctx.changelogDirs.filter((dir) => isWithinDir(dir, docsDir));
-			const docsPages = scanDocsDir(docsDir, ctx.entryPath, ctx.locale, excludedDirs);
+			const docsPages = scanDocsDir(docsDir, ctx.entryPath, ctx.locale, excludedDirs, ctx.publicPath);
 			if (docsPages.length === 0) continue;
 			next = docsPages;
 			break;
 		}
 		if (changelogConfig.enabled) {
-			const changelogPages = ctx.changelogDirs.flatMap((dir) => scanChangelogDir(dir, ctx.entryPath, changelogConfig.path, ctx.locale));
+			const changelogPages = ctx.changelogDirs.flatMap((dir) => scanChangelogDir(dir, ctx.entryPath, changelogConfig.path, ctx.locale, ctx.publicPath));
 			next = [...next, ...changelogPages];
 		}
 		indexesByLocale.set(key, next);
@@ -1885,16 +2009,21 @@ function createDocsAPI(options) {
 	}
 	async function getMarkdownDocument(ctx, requestedPath) {
 		const normalizedRequest = normalizeRequestedMarkdownPath(ctx.entryPath, requestedPath);
+		const normalizedPublicRequest = normalizePublicRequestedMarkdownPath(ctx, requestedPath);
 		const normalizedEntry = `/${normalizePathSegment(ctx.entryPath)}`;
 		const relativeSlug = normalizedRequest === normalizedEntry ? "" : normalizedRequest.slice(normalizedEntry.length).replace(/^\/+/, "");
 		for (const docsDir of ctx.docsDirs) if (isHiddenFolderIndexPageDir(relativeSlug ? path.join(docsDir, ...relativeSlug.split("/")) : docsDir)) return null;
 		for (const source of getMarkdownSources(ctx)) {
 			const page = findDocsMcpPage(ctx.entryPath, await source.getPages(), requestedPath);
-			if (page) return renderMarkdownDocument(page, { llmsEnabled: llmsConfig.enabled });
+			if (page) return renderMarkdownDocument(withPublicDocsUrl(page, ctx), { llmsEnabled: llmsConfig.enabled });
 		}
-		const fallbackPage = getIndexes(ctx).find((page) => normalizeUrlPath(page.url) === normalizedRequest);
-		if (fallbackPage) return renderMarkdownDocument(fallbackPage, { llmsEnabled: llmsConfig.enabled });
-		for (const page of getIndexes(ctx)) if (normalizePathSegment(page.url.replace(/^\/+/, "").replace(`${ctx.entryPath}/`, "")) === normalizePathSegment(requestedPath.replace(/^\/+/, "").replace(/\.md$/i, ""))) return renderMarkdownDocument(page, { llmsEnabled: llmsConfig.enabled });
+		const fallbackPage = getIndexes(ctx).find((page) => {
+			const pageUrl = normalizeUrlPath(page.url);
+			return pageUrl === normalizedRequest || pageUrl === normalizedPublicRequest;
+		});
+		if (fallbackPage) return renderMarkdownDocument(withPublicDocsUrl(fallbackPage, ctx), { llmsEnabled: llmsConfig.enabled });
+		const requestedSlug = normalizePublicDocsSlug(ctx, normalizedPublicRequest);
+		for (const page of getIndexes(ctx)) if (normalizePublicDocsSlug(ctx, page.url) === requestedSlug) return renderMarkdownDocument(withPublicDocsUrl(page, ctx), { llmsEnabled: llmsConfig.enabled });
 		return null;
 	}
 	function getLlmsContent(ctx) {
@@ -2049,15 +2178,14 @@ function createDocsAPI(options) {
 				manifest: readDocsSitemapManifest(root, sitemapConfig)
 			});
 			if (sitemapResponse) return sitemapResponse;
-			const markdownRequest = resolveMarkdownRequest(entry, url, request);
+			const markdownRequest = resolveMarkdownRequest(entry, url, request) ?? resolvePublicMarkdownRequest(entry, docsPath, url, request);
 			if (markdownRequest) {
 				const document = await getMarkdownDocument(ctx, markdownRequest.requestedPath);
 				const varyHeader = getDocsMarkdownVaryHeader(request);
-				const canonicalLinkHeader = getDocsMarkdownCanonicalLinkHeader({
+				const canonicalLinkHeader = getPublicMarkdownCanonicalLinkHeader({
 					origin: url.origin,
-					entry: ctx.entryPath,
-					requestedPath: markdownRequest.requestedPath,
-					locale: ctx.locale
+					ctx,
+					requestedPath: markdownRequest.requestedPath
 				});
 				if (!document) {
 					await emitDocsAnalyticsEvent(analytics, {

package/dist/docs-layout.mjs

@@ -65,6 +65,7 @@ function resolveDocsI18nConfig(i18n) {
 }
 function resolveDocsLocaleContext(config, locale) {
 	const entryBase = config.entry ?? "docs";
+	const publicPath = normalizeDocsPublicPath(config.docsPath, entryBase);
 	const i18n = resolveDocsI18nConfig(getDocsI18n(config));
 	const contentDir = config.contentDir;
 	function resolveContentDir(localeValue) {
@@ -77,15 +78,36 @@ function resolveDocsLocaleContext(config, locale) {
 	}
 	if (!i18n) return {
 		entryPath: entryBase,
+		publicPath,
 		docsDir: resolveContentDir()
 	};
 	const resolvedLocale = locale && i18n.locales.includes(locale) ? locale : i18n.defaultLocale;
 	return {
 		entryPath: entryBase,
+		publicPath,
 		locale: resolvedLocale,
 		docsDir: resolveContentDir(resolvedLocale)
 	};
 }
+function normalizeDocsPublicPath(value, entry) {
+	if (typeof value !== "string") return `/${entry.replace(/^\/+|\/+$/g, "") || "docs"}`;
+	const cleaned = value.trim();
+	if (cleaned === "" || cleaned === "/") return "";
+	return `/${cleaned.replace(/^\/+|\/+$/g, "")}`;
+}
+function publicDocsRoute(ctx, slugParts = []) {
+	const slug = slugParts.join("/");
+	if (!slug) return ctx.publicPath || "/";
+	return ctx.publicPath ? `${ctx.publicPath}/${slug}` : `/${slug}`;
+}
+function toPublicDocsPath(pathname, ctx) {
+	const normalizedEntry = `/${ctx.entryPath.replace(/^\/+|\/+$/g, "")}`;
+	const normalizedPath = pathname.replace(/\/+$/, "") || "/";
+	if (ctx.publicPath === normalizedEntry) return normalizedPath;
+	if (normalizedPath === normalizedEntry) return ctx.publicPath || "/";
+	if (normalizedPath.startsWith(`${normalizedEntry}/`)) return publicDocsRoute(ctx, normalizedPath.slice(normalizedEntry.length + 1).split("/").filter(Boolean));
+	return normalizedPath;
+}
 function getExcludedDocsDirs(config, ctx) {
 	const changelog = resolveChangelogConfig(config.changelog);
 	if (!changelog.enabled) return [];
@@ -123,7 +145,7 @@ function buildChangelogTree(config, ctx, flat = false) {
 	if (!changelog.enabled) return null;
 	const entries = readChangelogTreeEntries(config, ctx);
 	if (entries.length === 0) return null;
-	const url = `/${ctx.entryPath}/${changelog.path}`;
+	const url = publicDocsRoute(ctx, [changelog.path]);
 	const children = entries.map((entry) => ({
 		type: "page",
 		name: entry.title,
@@ -155,7 +177,7 @@ function buildTree(config, ctx, flat = false) {
 		if (data.hidden !== true) rootChildren.push({
 			type: "page",
 			name: data.title ?? "Documentation",
-			url: `/${ctx.entryPath}`,
+			url: publicDocsRoute(ctx),
 			icon: resolveIcon(data.icon, icons)
 		});
 	}
@@ -167,7 +189,7 @@ function buildTree(config, ctx, flat = false) {
 		if (!fs.existsSync(pagePath)) return null;
 		const data = readFrontmatter(pagePath);
 		const slug = [...baseSlug, name];
-		const url = `/${ctx.entryPath}/${slug.join("/")}`;
+		const url = publicDocsRoute(ctx, slug);
 		const icon = resolveIcon(data.icon, icons);
 		const displayName = data.title ?? name.replace(/-/g, " ");
 		const hasChildren = hasChildPages(full, excludedDirs);
@@ -318,7 +340,7 @@ function buildLastModifiedMap(config, ctx) {
 		if (isExcludedDir(dir, excludedDirs)) return;
 		const pagePath = path.join(dir, "page.mdx");
 		if (fs.existsSync(pagePath)) {
-			const url = slugParts.length === 0 ? `/${ctx.entryPath}` : `/${ctx.entryPath}/${slugParts.join("/")}`;
+			const url = publicDocsRoute(ctx, slugParts);
 			map[url] = formatDate(fs.statSync(pagePath).mtime);
 		}
 		for (const name of fs.readdirSync(dir)) {
@@ -344,7 +366,7 @@ function buildDescriptionMap(config, ctx) {
 		if (fs.existsSync(pagePath)) {
 			const desc = readFrontmatter(pagePath).description;
 			if (desc) {
-				const url = slugParts.length === 0 ? `/${ctx.entryPath}` : `/${ctx.entryPath}/${slugParts.join("/")}`;
+				const url = publicDocsRoute(ctx, slugParts);
 				map[url] = desc;
 			}
 		}
@@ -368,7 +390,7 @@ function buildReadingTimeMap(config, ctx, options) {
 			const { data, content } = matter(fs.readFileSync(pagePath, "utf-8"));
 			const minutes = resolvePageReadingTime(data, resolveDocsAgentMdxContent(content, "human"), options);
 			if (typeof minutes === "number") {
-				const url = slugParts.length === 0 ? `/${ctx.entryPath}` : `/${ctx.entryPath}/${slugParts.join("/")}`;
+				const url = publicDocsRoute(ctx, slugParts);
 				map[url] = minutes;
 			}
 		}
@@ -394,7 +416,7 @@ function buildStructuredDataMap(config, ctx) {
 		const pagePath = findDocsPageFile(dir);
 		if (pagePath) {
 			const { data } = matter(fs.readFileSync(pagePath, "utf-8"));
-			const route = slugParts.length === 0 ? `/${ctx.entryPath}` : `/${ctx.entryPath}/${slugParts.join("/")}`;
+			const route = publicDocsRoute(ctx, slugParts);
 			const title = typeof data.title === "string" ? data.title : slugParts.at(-1)?.replace(/-/g, " ") || "Documentation";
 			const description = typeof data.description === "string" ? data.description : void 0;
 			const stat = fs.statSync(pagePath);
@@ -610,9 +632,9 @@ function createDocsLayout(config, options) {
 	const activeLocale = localeContext.locale ?? i18n?.defaultLocale;
 	const docsApiUrl = withLangInUrl("/api/docs", activeLocale);
 	const changelogConfig = resolveChangelogConfig(config.changelog);
-	const changelogBasePath = changelogConfig.enabled ? `/${localeContext.entryPath}/${changelogConfig.path}` : void 0;
+	const changelogBasePath = changelogConfig.enabled ? publicDocsRoute(localeContext, [changelogConfig.path]) : void 0;
 	const navTitle = config.nav?.title ?? "Docs";
-	const navUrl = withLangInUrl(config.nav?.url ?? `/${localeContext.entryPath}`, activeLocale);
+	const navUrl = withLangInUrl(config.nav?.url ? toPublicDocsPath(config.nav.url, localeContext) : publicDocsRoute(localeContext), activeLocale);
 	const themeSwitch = resolveThemeSwitch(config.themeToggle);
 	const toggleConfig = typeof config.themeToggle === "object" ? config.themeToggle : void 0;
 	const forcedTheme = themeSwitch.enabled === false && toggleConfig?.default && toggleConfig.default !== "system" ? toggleConfig.default : void 0;
@@ -757,6 +779,7 @@ function createDocsLayout(config, options) {
 						breadcrumbEnabled,
 						changelogBasePath,
 						entry: localeContext.entryPath,
+						publicPath: localeContext.publicPath,
 						locale: activeLocale,
 						copyMarkdown: copyMarkdownEnabled,
 						openDocs: openDocsEnabled,

package/dist/docs-page-client.d.mts

@@ -16,6 +16,8 @@ interface DocsPageClientProps {
   changelogBasePath?: string;
   /** The docs entry folder name (e.g. "docs") — used to strip from breadcrumb */
   entry?: string;
+  /** Public docs route prefix. Empty string means docs render from the site root. */
+  publicPath?: string;
   /** Active locale (used for llms.txt links) */
   locale?: string;
   copyMarkdown?: boolean;
@@ -79,6 +81,7 @@ declare function DocsPageClient({
   breadcrumbEnabled,
   changelogBasePath,
   entry,
+  publicPath,
   locale,
   copyMarkdown,
   openDocs,

package/dist/docs-page-client.mjs

@@ -28,17 +28,17 @@ const agentLlmsDirectiveStyle = {
 * Path-based breadcrumb that shows only parent / current folder.
 * Skips the entry segment (e.g. "docs"). Parent is clickable.
 */
-function PathBreadcrumb({ pathname, entry, locale }) {
+function PathBreadcrumb({ pathname, publicPath, locale }) {
 	const router = useRouter();
 	const segments = pathname.split("/").filter(Boolean);
-	const entryParts = entry.split("/").filter(Boolean);
-	const contentSegments = segments.slice(entryParts.length);
+	const publicParts = publicPath.split("/").filter(Boolean);
+	const contentSegments = publicParts.length > 0 && segments.slice(0, publicParts.length).join("/") === publicParts.join("/") ? segments.slice(publicParts.length) : segments;
 	if (contentSegments.length < 2) return null;
 	const parentSegment = contentSegments[contentSegments.length - 2];
 	const currentSegment = contentSegments[contentSegments.length - 1];
 	const parentLabel = parentSegment.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 	const currentLabel = currentSegment.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-	const localizedParentUrl = withLangInUrl("/" + [...segments.slice(0, entryParts.length), ...contentSegments.slice(0, -1)].join("/"), locale);
+	const localizedParentUrl = withLangInUrl("/" + [...publicParts, ...contentSegments.slice(0, -1)].filter(Boolean).join("/"), locale);
 	return /* @__PURE__ */ jsxs("nav", {
 		className: "fd-breadcrumb",
 		"aria-label": "Breadcrumb",
@@ -102,6 +102,94 @@ function localizeInternalLinks(root, locale) {
 		} catch {}
 	}
 }
+function normalizePublicDocsPath(value, entry) {
+	if (typeof value !== "string") return `/${entry.replace(/^\/+|\/+$/g, "") || "docs"}`;
+	const cleaned = value.trim();
+	if (cleaned === "" || cleaned === "/") return "";
+	return `/${cleaned.replace(/^\/+|\/+$/g, "")}`;
+}
+function toPublicDocsPath(pathname, entry, publicPath) {
+	const normalizedEntry = `/${entry.replace(/^\/+|\/+$/g, "") || "docs"}`;
+	const normalizedPath = pathname.replace(/\/+$/, "") || "/";
+	if (publicPath === normalizedEntry) return normalizedPath;
+	if (normalizedPath === normalizedEntry) return publicPath || "/";
+	if (normalizedPath.startsWith(`${normalizedEntry}/`)) {
+		const suffix = normalizedPath.slice(normalizedEntry.length + 1);
+		return publicPath ? `${publicPath}/${suffix}` : `/${suffix}`;
+	}
+	return normalizedPath;
+}
+function rewriteDocsPathLinks(root, entry, publicPath) {
+	const anchors = root.querySelectorAll("a[href]:not([data-fd-docspath=\"true\"])");
+	for (const anchor of anchors) {
+		const href = anchor.getAttribute("href");
+		if (!href || href.startsWith("#")) continue;
+		if (/^(mailto:|tel:|javascript:)/i.test(href)) continue;
+		try {
+			const url = new URL(href, window.location.origin);
+			if (url.origin !== window.location.origin) continue;
+			const nextPath = toPublicDocsPath(url.pathname, entry, publicPath);
+			if (nextPath === url.pathname) continue;
+			anchor.href = `${nextPath}${url.search}${url.hash}`;
+			anchor.dataset.fdDocspath = "true";
+		} catch {}
+	}
+}
+function normalizeCurrentPath(pathname) {
+	return pathname.replace(/\/+$/, "") || "/";
+}
+function syncDocsPathActiveLinks(root, entry, publicPath) {
+	const currentPath = normalizeCurrentPath(window.location.pathname);
+	const anchors = root.querySelectorAll("a[data-active][href]");
+	for (const anchor of anchors) {
+		const href = anchor.getAttribute("href");
+		if (!href || href.startsWith("#")) continue;
+		try {
+			const url = new URL(href, window.location.origin);
+			if (url.origin !== window.location.origin) continue;
+			if (!isDocsNavigationPath(url.pathname, entry, publicPath)) continue;
+			const publicHrefPath = normalizeCurrentPath(toPublicDocsPath(url.pathname, entry, publicPath));
+			anchor.dataset.active = publicHrefPath === currentPath ? "true" : "false";
+		} catch {}
+	}
+}
+function isFrameworkPath(pathname) {
+	return pathname.startsWith("/_next") || pathname.startsWith("/api") || pathname.startsWith("/.well-known") || pathname === "/mcp" || pathname === "/llms.txt" || pathname === "/llms-full.txt" || pathname === "/robots.txt" || pathname === "/sitemap.xml" || pathname === "/sitemap.md" || pathname === "/AGENTS.md" || pathname === "/AGENT.md" || pathname === "/skill.md" || /\/[^/]+\.[^/]+$/.test(pathname);
+}
+function isDocsNavigationPath(pathname, entry, publicPath) {
+	if (isFrameworkPath(pathname)) return false;
+	const normalizedEntry = `/${entry.replace(/^\/+|\/+$/g, "") || "docs"}`;
+	if (pathname === normalizedEntry || pathname.startsWith(`${normalizedEntry}/`)) return true;
+	if (publicPath === "") return pathname.startsWith("/");
+	return pathname === publicPath || pathname.startsWith(`${publicPath}/`);
+}
+function installDocsPathNavigationGuard(entry, publicPath) {
+	if (publicPath === `/${entry.replace(/^\/+|\/+$/g, "") || "docs"}`) return void 0;
+	function onClick(event) {
+		if (event.defaultPrevented) return;
+		if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+		const anchor = (event.target instanceof Element ? event.target : null)?.closest("a[href]");
+		if (!anchor) return;
+		if (anchor.target && anchor.target !== "_self") return;
+		if (anchor.hasAttribute("download")) return;
+		const href = anchor.getAttribute("href");
+		if (!href || href.startsWith("#")) return;
+		if (/^(mailto:|tel:|javascript:)/i.test(href)) return;
+		try {
+			const url = new URL(href, window.location.origin);
+			if (url.origin !== window.location.origin) return;
+			if (!isDocsNavigationPath(url.pathname, entry, publicPath)) return;
+			const nextPath = toPublicDocsPath(url.pathname, entry, publicPath);
+			if (nextPath === url.pathname) return;
+			const nextHref = `${nextPath}${url.search}${url.hash}`;
+			if (nextHref === `${window.location.pathname}${window.location.search}${window.location.hash}`) return;
+			event.preventDefault();
+			window.location.assign(nextHref);
+		} catch {}
+	}
+	document.addEventListener("click", onClick, true);
+	return () => document.removeEventListener("click", onClick, true);
+}
 function decodeHashTarget(hash) {
 	const value = hash.startsWith("#") ? hash.slice(1) : hash;
 	try {
@@ -175,13 +263,14 @@ function TitleDecorations({ description, belowTitle }) {
 	if (!description && !belowTitle) return null;
 	return /* @__PURE__ */ jsx(Fragment$1, { children: Children.toArray([description, belowTitle].filter(Boolean)) });
 }
-function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled = true, changelogBasePath, entry = "docs", locale, copyMarkdown = false, openDocs = false, openDocsProviders, pageActionsPosition = "below-title", pageActionsAlignment = "left", githubUrl, contentDir, githubBranch = "main", githubDirectory, editOnGithubUrl, lastModifiedMap, lastModified: lastModifiedProp, readingTimeMap, readingTime: readingTimeProp, structuredDataMap, structuredData: structuredDataProp, readingTimeEnabled = false, lastUpdatedEnabled = true, lastUpdatedPosition = "footer", llmsTxtEnabled = false, descriptionMap, description, feedbackEnabled = false, feedbackQuestion, feedbackPlaceholder, feedbackPositiveLabel, feedbackNegativeLabel, feedbackSubmitLabel, feedbackOnFeedback, analytics = false, children }) {
+function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled = true, changelogBasePath, entry = "docs", publicPath, locale, copyMarkdown = false, openDocs = false, openDocsProviders, pageActionsPosition = "below-title", pageActionsAlignment = "left", githubUrl, contentDir, githubBranch = "main", githubDirectory, editOnGithubUrl, lastModifiedMap, lastModified: lastModifiedProp, readingTimeMap, readingTime: readingTimeProp, structuredDataMap, structuredData: structuredDataProp, readingTimeEnabled = false, lastUpdatedEnabled = true, lastUpdatedPosition = "footer", llmsTxtEnabled = false, descriptionMap, description, feedbackEnabled = false, feedbackQuestion, feedbackPlaceholder, feedbackPositiveLabel, feedbackNegativeLabel, feedbackSubmitLabel, feedbackOnFeedback, analytics = false, children }) {
 	const fdTocStyle = tocStyle === "directional" ? "clerk" : void 0;
 	const [toc, setToc] = useState([]);
 	const [titlePortalHost, setTitlePortalHost] = useState(null);
 	const [browserPath, setBrowserPath] = useState(null);
 	const pathname = usePathname();
 	const activeLocale = resolveClientLocale(useWindowSearchParams(), locale);
+	const resolvedPublicPath = normalizePublicDocsPath(publicPath, entry);
 	const llmsLangQuery = activeLocale ? `?lang=${encodeURIComponent(activeLocale)}` : "";
 	const pageDescription = description ?? descriptionMap?.[pathname.replace(/\/$/, "") || "/"];
 	const normalizedPath = (browserPath ?? pathname).replace(/\/$/, "") || "/";
@@ -207,6 +296,9 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 		isChangelogRoute,
 		normalizedPath
 	]);
+	useEffect(() => {
+		return installDocsPathNavigationGuard(entry, resolvedPublicPath);
+	}, [entry, resolvedPublicPath]);
 	const resolvedReadingTime = !isChangelogRoute ? readingTimeProp !== void 0 ? readingTimeProp : readingTimeEnabled ? matchedReadingTime : void 0 : void 0;
 	const effectiveTocEnabled = isChangelogRoute ? false : tocEnabled;
 	const effectiveBreadcrumbEnabled = isChangelogRoute ? false : breadcrumbEnabled;
@@ -225,17 +317,22 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 		return () => cancelAnimationFrame(timer);
 	}, [effectiveTocEnabled, pathname]);
 	useEffect(() => {
-		if (!activeLocale) return;
 		const timer = requestAnimationFrame(() => {
-			const container = document.getElementById("nd-page");
-			if (!container) return;
-			localizeInternalLinks(container, activeLocale);
+			const root = document.body;
+			if (!root) return;
+			rewriteDocsPathLinks(root, entry, resolvedPublicPath);
+			syncDocsPathActiveLinks(root, entry, resolvedPublicPath);
+			if (!activeLocale) return;
+			localizeInternalLinks(root, activeLocale);
 		});
 		return () => cancelAnimationFrame(timer);
 	}, [
 		activeLocale,
+		browserPath,
 		children,
-		pathname
+		entry,
+		pathname,
+		resolvedPublicPath
 	]);
 	useEffect(() => {
 		setBrowserPath(window.location.pathname);
@@ -383,7 +480,7 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 			children: [
 				effectiveBreadcrumbEnabled && /* @__PURE__ */ jsx(PathBreadcrumb, {
 					pathname,
-					entry,
+					publicPath: resolvedPublicPath,
 					locale: activeLocale
 				}),
 				showActionsAboveTitle && /* @__PURE__ */ jsxs("div", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.1.108",
+  "version": "0.1.109",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -139,7 +139,7 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@farming-labs/docs": "0.1.108"
+    "@farming-labs/docs": "0.1.109"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",