@farming-labs/theme 0.1.129 → 0.1.131

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 { DEFAULT_SITEMAP_MD_DOCS_ROUTE, 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 { DEFAULT_SITEMAP_MD_DOCS_ROUTE, buildDocsAskAIContext, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsRobotsResponse, createDocsSitemapResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, formatDocsAskAIPackageHints, getDocsLlmsTxtMaxCharsIssue, getDocsMarkdownVaryHeader, hasDocsMarkdownSignatureAgent, normalizeDocsRelated, performDocsSearch, renderDocsLlmsTxt, renderDocsMarkdownDocument, renderDocsMarkdownNotFound, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMarkdownRecovery, 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
@@ -992,6 +992,13 @@ function acceptsMarkdown(request) {
 		return Number.isFinite(quality) ? quality > 0 : true;
 	});
 }
+function resolveMarkdownHeaderDelivery(request) {
+	if (hasDocsMarkdownSignatureAgent(request)) return "signature_agent";
+	if (acceptsMarkdown(request)) return "accept_header";
+	const agentDetection = detectDocsMarkdownAgentRequest(request);
+	if (!agentDetection.detected) return null;
+	return agentDetection.method === "heuristic" ? "heuristic" : "user_agent";
+}
 function resolveMarkdownRequest(entry, url, request) {
 	if (url.searchParams.get("format")?.trim() === "markdown") return {
 		requestedPath: url.searchParams.get("path")?.trim() ?? "",
@@ -1008,9 +1015,9 @@ function resolveMarkdownRequest(entry, url, request) {
 		requestedPath: pathname.slice(slugPrefix.length, -3),
 		delivery: "md_route"
 	};
-	const hasSignatureAgent = hasDocsMarkdownSignatureAgent(request);
-	if (acceptsMarkdown(request) || hasSignatureAgent) {
-		const delivery = hasSignatureAgent ? "signature_agent" : "accept_header";
+	const headerDelivery = resolveMarkdownHeaderDelivery(request);
+	if (headerDelivery) {
+		const delivery = headerDelivery;
 		if (pathname === normalizedEntry) return {
 			requestedPath: "",
 			delivery
@@ -1078,9 +1085,9 @@ function resolvePublicMarkdownRequest(entry, docsPath, url, request) {
 			requestedPath: pathname.slice(1, -3),
 			delivery: "md_route"
 		};
-		const hasSignatureAgent = hasDocsMarkdownSignatureAgent(request);
-		if (acceptsMarkdown(request) || hasSignatureAgent) {
-			const delivery = hasSignatureAgent ? "signature_agent" : "accept_header";
+		const headerDelivery = resolveMarkdownHeaderDelivery(request);
+		if (headerDelivery) {
+			const delivery = headerDelivery;
 			return {
 				requestedPath: pathname === "/" ? "" : pathname.slice(1),
 				delivery
@@ -1097,9 +1104,9 @@ function resolvePublicMarkdownRequest(entry, docsPath, url, request) {
 		requestedPath: pathname.slice(slugPrefix.length, -3),
 		delivery: "md_route"
 	};
-	const hasSignatureAgent = hasDocsMarkdownSignatureAgent(request);
-	if (acceptsMarkdown(request) || hasSignatureAgent) {
-		const delivery = hasSignatureAgent ? "signature_agent" : "accept_header";
+	const headerDelivery = resolveMarkdownHeaderDelivery(request);
+	if (headerDelivery) {
+		const delivery = headerDelivery;
 		if (pathname === docsPath) return {
 			requestedPath: "",
 			delivery
@@ -1112,14 +1119,10 @@ function resolvePublicMarkdownRequest(entry, docsPath, url, request) {
 	return null;
 }
 function renderMarkdownDocument(page, options = {}) {
-	if ("agentRawContent" in page && page.agentRawContent !== void 0) return page.agentRawContent;
-	const relatedLines = renderDocsRelatedMarkdownLines(page.related);
-	const lines = [`# ${page.title}`, `URL: ${page.url}`];
-	if (options.llmsEnabled !== false) lines.push("LLM index: /llms.txt");
-	if (page.description) lines.push(`Description: ${page.description}`);
-	lines.push(...relatedLines);
-	lines.push("", page.agentFallbackRawContent ?? page.rawContent ?? page.content);
-	return lines.join("\n");
+	return renderDocsMarkdownDocument(page, {
+		llms: options.llmsEnabled !== false,
+		sitemap: options.sitemap
+	});
 }
 function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitemap, robots, openapi }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
@@ -2020,15 +2023,24 @@ function createDocsAPI(options) {
 		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(withPublicDocsUrl(page, ctx), { llmsEnabled: llmsConfig.enabled });
+			if (page) return renderMarkdownDocument(withPublicDocsUrl(page, ctx), {
+				llmsEnabled: llmsConfig.enabled,
+				sitemap: sitemapConfig
+			});
 		}
 		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 });
+		if (fallbackPage) return renderMarkdownDocument(withPublicDocsUrl(fallbackPage, ctx), {
+			llmsEnabled: llmsConfig.enabled,
+			sitemap: sitemapConfig
+		});
 		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 });
+		for (const page of getIndexes(ctx)) if (normalizePublicDocsSlug(ctx, page.url) === requestedSlug) return renderMarkdownDocument(withPublicDocsUrl(page, ctx), {
+			llmsEnabled: llmsConfig.enabled,
+			sitemap: sitemapConfig
+		});
 		return null;
 	}
 	function getLlmsContent(ctx) {
@@ -2193,6 +2205,13 @@ function createDocsAPI(options) {
 					requestedPath: markdownRequest.requestedPath
 				});
 				if (!document) {
+					const recoveryPages = getIndexes(ctx).map((page) => withPublicDocsUrl(page, ctx));
+					const recovery = resolveDocsMarkdownRecovery({
+						entry,
+						requestedPath: markdownRequest.requestedPath,
+						pages: recoveryPages,
+						sitemap: sitemapConfig
+					});
 					await emitDocsAnalyticsEvent(analytics, {
 						type: "agent_read",
 						source: "server",
@@ -2217,12 +2236,21 @@ function createDocsAPI(options) {
 							found: false
 						}
 					});
+					if (recovery.redirect) return new Response(null, {
+						status: 307,
+						headers: {
+							Location: new URL(recovery.redirect.markdownUrl, url.origin).toString(),
+							...varyHeader ? { Vary: varyHeader } : {},
+							"X-Robots-Tag": "noindex"
+						}
+					});
 					return new Response(renderDocsMarkdownNotFound({
 						entry,
 						requestedPath: markdownRequest.requestedPath,
+						pages: recoveryPages,
 						sitemap: sitemapConfig
 					}), {
-						status: 404,
+						status: 200,
 						headers: {
 							"Content-Type": "text/markdown; charset=utf-8",
 							...varyHeader ? { Vary: varyHeader } : {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.1.129",
+  "version": "0.1.131",
   "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.129"
+    "@farming-labs/docs": "0.1.131"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",