@farming-labs/theme 0.1.73 → 0.1.75

package/dist/docs-api.d.mts

@@ -1,4 +1,4 @@
-import { ChangelogConfig, DocsAnalyticsConfig, DocsI18nConfig, DocsMcpConfig, DocsObservabilityConfig, DocsSearchConfig, FeedbackConfig, OrderingItem } from "@farming-labs/docs";
+import { ChangelogConfig, DocsAnalyticsConfig, DocsAskAIMcpConfig, DocsI18nConfig, DocsMcpConfig, DocsObservabilityConfig, DocsSearchConfig, DocsSitemapConfig, FeedbackConfig, OrderingItem } from "@farming-labs/docs";
 
 //#region src/docs-api.d.ts
 interface AIProviderConfig {
@@ -28,6 +28,7 @@ interface AIOptions {
   /** Default apiKey when no per-model provider is configured. */
   apiKey?: string;
   maxResults?: number;
+  useMcp?: boolean | DocsAskAIMcpConfig;
 }
 interface DocsAPIOptions {
   rootDir?: string;
@@ -53,6 +54,8 @@ interface DocsAPIOptions {
   feedback?: boolean | FeedbackConfig;
   /** MCP configuration used for the agent discovery spec. */
   mcp?: boolean | DocsMcpConfig;
+  /** Sitemap configuration used for sitemap.xml and sitemap.md. */
+  sitemap?: boolean | DocsSitemapConfig;
 }
 interface DocsMCPAPIOptions {
   rootDir?: string;

package/dist/docs-api.mjs

@@ -3,8 +3,8 @@ 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, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, formatDocsAskAIPackageHints, normalizeDocsRelated, performDocsSearch, renderDocsRelatedMarkdownLines, resolveChangelogConfig, resolveDocsI18n, resolveDocsLocale, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig } from "@farming-labs/docs";
-import { createDocsMcpHttpHandler, createFilesystemDocsMcpSource, resolveDocsMcpConfig } from "@farming-labs/docs/server";
+import { buildDocsAskAIContext, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsSitemapResponse, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, formatDocsAskAIPackageHints, normalizeDocsRelated, performDocsSearch, renderDocsRelatedMarkdownLines, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsI18n, resolveDocsLocale, resolveDocsSitemapConfig, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig } from "@farming-labs/docs";
+import { createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
 /**
@@ -172,10 +172,11 @@ function isSearchEnabled(search) {
 	if (search && typeof search === "object" && search.enabled === false) return false;
 	return true;
 }
-function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms }) {
+function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, sitemap }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const localesEnabled = i18n !== null;
 	const searchEnabled = isSearchEnabled(search);
+	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: llms.baseUrl });
 	return {
 		version: "1",
 		name: "@farming-labs/docs",
@@ -201,6 +202,7 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms }) {
 			skills: true,
 			mcp: mcp.enabled,
 			search: searchEnabled,
+			sitemap: sitemapConfig.enabled,
 			agentFeedback: feedback.enabled,
 			locales: localesEnabled
 		},
@@ -236,6 +238,20 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms }) {
 			wellKnownTxt: DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE,
 			wellKnownFull: DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE
 		},
+		sitemap: {
+			enabled: sitemapConfig.enabled,
+			xml: {
+				enabled: sitemapConfig.xml.enabled,
+				route: sitemapConfig.xml.route,
+				api: `${DEFAULT_DOCS_API_ROUTE}?format=sitemap-xml`
+			},
+			markdown: {
+				enabled: sitemapConfig.markdown.enabled,
+				route: sitemapConfig.markdown.route,
+				wellKnownRoute: sitemapConfig.markdown.wellKnownRoute,
+				api: `${DEFAULT_DOCS_API_ROUTE}?format=sitemap-md`
+			}
+		},
 		search: {
 			enabled: searchEnabled,
 			endpoint: `${DEFAULT_DOCS_API_ROUTE}?query={query}`,
@@ -413,6 +429,7 @@ function readAIConfig(root) {
 			const baseUrlMatch = content.match(/ai\s*:\s*\{[^}]*baseUrl\s*:\s*["']([^"']+)["']/s);
 			const apiKeyMatch = content.match(/ai\s*:\s*\{[^}]*apiKey\s*:\s*process\.env\.(\w+)/s);
 			const maxResultsMatch = content.match(/ai\s*:\s*\{[^}]*maxResults\s*:\s*(\d+)/s);
+			const useMcpMatch = content.match(/ai\s*:\s*\{[^}]*useMcp\s*:\s*(true|false)/s);
 			const systemPromptMatch = content.match(/ai\s*:\s*\{[^}]*systemPrompt\s*:\s*["'`]([^"'`]+)["'`]/s);
 			const packageNameMatch = content.match(/ai\s*:\s*\{[^}]*packageName\s*:\s*["'`]([^"'`]+)["'`]/s);
 			const docsUrlMatch = content.match(/ai\s*:\s*\{[^}]*docsUrl\s*:\s*["'`]([^"'`]+)["'`]/s);
@@ -422,6 +439,7 @@ function readAIConfig(root) {
 				baseUrl: baseUrlMatch?.[1],
 				apiKey: apiKeyMatch?.[1] ? process.env[apiKeyMatch[1]] : void 0,
 				maxResults: maxResultsMatch ? parseInt(maxResultsMatch[1], 10) : void 0,
+				useMcp: useMcpMatch ? useMcpMatch[1] === "true" : void 0,
 				systemPrompt: systemPromptMatch?.[1],
 				packageName: packageNameMatch?.[1],
 				docsUrl: docsUrlMatch?.[1]
@@ -735,6 +753,8 @@ function scanDocsDir(docsDir, entry, locale, excludedDirs = []) {
 					rawContent,
 					agentFallbackRawContent: agentRawContent !== rawContent ? agentRawContent : void 0,
 					url,
+					sourcePath: pageSource.replace(/\\/g, "/"),
+					lastModified: fs.statSync(pageSource).mtime.toISOString(),
 					locale
 				});
 			}
@@ -893,11 +913,12 @@ function renderMarkdownDocument(page) {
 	lines.push("", page.agentFallbackRawContent ?? page.rawContent ?? page.content);
 	return lines.join("\n");
 }
-function renderSkillDocument({ origin, entry, search, mcp, feedback, llms }) {
+function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitemap }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const siteTitle = compactSkillText(llms.siteTitle ?? "Documentation");
 	const siteDescription = llms.siteDescription ? compactSkillText(llms.siteDescription) : void 0;
 	const searchEnabled = isSearchEnabled(search);
+	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: llms.baseUrl });
 	const lines = [
 		"---",
 		"name: docs",
@@ -912,10 +933,18 @@ function renderSkillDocument({ origin, entry, search, mcp, feedback, llms }) {
 	lines.push("", "## When To Use", "Use this skill when you need to read or implement against this documentation site.", "", "## Start Here", `- Fetch ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${DEFAULT_AGENT_SPEC_ROUTE}.`, `- Fetch /${normalizedEntry}.md for the root docs page.`, `- Fetch /${normalizedEntry}/{slug}.md for page-specific context.`, "- You can also request text/markdown from normal page URLs.");
 	if (searchEnabled) lines.push(`- Search with ${DEFAULT_DOCS_API_ROUTE}?query={query} when you do not know the page.`);
 	if (llms.enabled) lines.push(`- Use ${DEFAULT_LLMS_TXT_ROUTE} for a compact docs index.`, `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} for full markdown context.`);
+	if (sitemapConfig.enabled) {
+		if (sitemapConfig.xml.enabled) lines.push(`- Use ${sitemapConfig.xml.route} to check canonical page freshness.`);
+		if (sitemapConfig.markdown.enabled) lines.push(`- Use ${sitemapConfig.markdown.route} for a semantic docs map.`);
+	}
 	if (mcp.enabled) lines.push(`- Use ${DEFAULT_MCP_WELL_KNOWN_ROUTE} or ${DEFAULT_MCP_PUBLIC_ROUTE} for MCP tools when your environment supports MCP.`);
 	if (feedback.enabled) lines.push(`- Read ${feedback.schemaRoute} before posting agent feedback to ${feedback.route}.`);
 	lines.push("", "## Routes", `- Skill document: ${DEFAULT_SKILL_MD_ROUTE}`, `- Skill well-known alias: ${DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE}`, `- Skill API format: ${DEFAULT_DOCS_API_ROUTE}?format=skill`, `- Agent discovery: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}`, `- Agent discovery fallback: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}`, `- Markdown root: /${normalizedEntry}.md`, `- Markdown pages: /${normalizedEntry}/{slug}.md`);
 	if (llms.enabled) lines.push(`- llms.txt: ${DEFAULT_LLMS_TXT_ROUTE}`, `- llms-full.txt: ${DEFAULT_LLMS_FULL_TXT_ROUTE}`, `- llms well-known aliases: ${DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE}, ${DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE}`);
+	if (sitemapConfig.enabled) {
+		if (sitemapConfig.xml.enabled) lines.push(`- Sitemap XML: ${sitemapConfig.xml.route}`);
+		if (sitemapConfig.markdown.enabled) lines.push(`- Sitemap Markdown: ${sitemapConfig.markdown.route}`, `- Sitemap well-known alias: ${sitemapConfig.markdown.wellKnownRoute}`);
+	}
 	if (mcp.enabled) lines.push(`- MCP: ${DEFAULT_MCP_PUBLIC_ROUTE}, ${DEFAULT_MCP_WELL_KNOWN_ROUTE}`);
 	lines.push("", "## Reusable Framework Skills", "For framework setup, CLI, page actions, Ask AI, or configuration work, install the reusable Farming Labs skills:", "", "```sh", "npx skills add farming-labs/docs", "```");
 	return lines.join("\n");
@@ -1451,6 +1480,31 @@ function readLlmsTxtConfig(root) {
 	}
 	return { enabled: false };
 }
+function readSitemapConfig(root) {
+	for (const ext of FILE_EXTS) {
+		const configPath = path.join(root, `docs.config.${ext}`);
+		if (!fs.existsSync(configPath)) continue;
+		try {
+			const content = fs.readFileSync(configPath, "utf-8");
+			if (!content.includes("sitemap")) return void 0;
+			if (/sitemap\s*:\s*false/.test(content)) return false;
+			if (/sitemap\s*:\s*true/.test(content)) return true;
+			const sitemapBlock = content.match(/sitemap\s*:\s*\{([\s\S]*?)\n\s*\}/)?.[1] ?? "";
+			const routePrefix = sitemapBlock.match(/routePrefix\s*:\s*["']([^"']+)["']/)?.[1];
+			const baseUrl = sitemapBlock.match(/baseUrl\s*:\s*["']([^"']+)["']/)?.[1];
+			const manifestPath = sitemapBlock.match(/manifestPath\s*:\s*["']([^"']+)["']/)?.[1];
+			const enabledMatch = sitemapBlock.match(/enabled\s*:\s*(true|false)/);
+			return {
+				enabled: enabledMatch ? enabledMatch[1] === "true" : true,
+				routePrefix,
+				baseUrl,
+				manifestPath
+			};
+		} catch {
+			return;
+		}
+	}
+}
 function generateLlmsTxt(indexes, options) {
 	const { siteTitle = "Documentation", siteDescription, baseUrl = "" } = options;
 	let llmsTxt = `# ${siteTitle}\n\n`;
@@ -1511,6 +1565,7 @@ function createDocsAPI(options) {
 	const aiConfig = options?.ai ?? readAIConfig(root);
 	const searchConfig = options?.search;
 	const llmsConfig = readLlmsTxtConfig(root);
+	const sitemapConfig = options?.sitemap ?? readSitemapConfig(root);
 	const mcpConfig = resolveDocsMcpConfig(options?.mcp ?? readMcpConfig(root), { defaultName: llmsConfig.siteTitle ?? "Documentation" });
 	function resolveDocsDirCandidates(locale) {
 		const relativeCandidates = /* @__PURE__ */ new Set();
@@ -1650,7 +1705,8 @@ function createDocsAPI(options) {
 					search: searchConfig,
 					mcp: mcpConfig,
 					feedback: agentFeedbackConfig,
-					llms: llmsConfig
+					llms: llmsConfig,
+					sitemap: sitemapConfig
 				}), { headers: {
 					"Cache-Control": "public, max-age=0, s-maxage=3600",
 					"X-Robots-Tag": "noindex"
@@ -1692,13 +1748,24 @@ function createDocsAPI(options) {
 					search: searchConfig,
 					mcp: mcpConfig,
 					feedback: agentFeedbackConfig,
-					llms: llmsConfig
+					llms: llmsConfig,
+					sitemap: sitemapConfig
 				}), { headers: {
 					"Content-Type": "text/markdown; charset=utf-8",
 					"Cache-Control": "public, max-age=0, s-maxage=3600",
 					"X-Robots-Tag": "noindex"
 				} });
 			}
+			const sitemapResponse = createDocsSitemapResponse({
+				request,
+				sitemap: sitemapConfig,
+				entry,
+				siteTitle: llmsConfig.siteTitle ?? "Documentation",
+				baseUrl: llmsConfig.baseUrl ?? url.origin,
+				pages: getIndexes(ctx),
+				manifest: readDocsSitemapManifest(root, sitemapConfig)
+			});
+			if (sitemapResponse) return sitemapResponse;
 			const markdownRequest = resolveMarkdownRequest(entry, url, request);
 			if (markdownRequest) {
 				const document = await getMarkdownDocument(ctx, markdownRequest.requestedPath);
@@ -1901,7 +1968,14 @@ function createDocsAPI(options) {
 				return Response.json({ error: "AI is not enabled. Set `ai: { enabled: true }` in your docs.config to enable it." }, { status: 404 });
 			}
 			const ctx = resolveContextFromRequest(request);
-			return handleAskAI(request, getIndexes(ctx), aiConfig, resolveSearchRequestConfig(searchConfig, request.url), analytics, observability, { locale: ctx.locale });
+			return handleAskAI(request, getIndexes(ctx), aiConfig, resolveAskAISearchRequestConfig({
+				search: searchConfig,
+				useMcp: aiConfig.useMcp,
+				mcpEndpoint: mcpConfig.route,
+				mcpEnabled: mcpConfig.enabled,
+				mcpSearchEnabled: mcpConfig.tools.searchDocs,
+				requestUrl: request.url
+			}), analytics, observability, { locale: ctx.locale });
 		}
 	};
 }

package/package.json

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