@farming-labs/theme 0.1.86 → 0.1.89

package/dist/docs-api.d.mts

@@ -1,4 +1,4 @@
-import { ChangelogConfig, DocsAnalyticsConfig, DocsAskAIMcpConfig, DocsI18nConfig, DocsMcpConfig, DocsObservabilityConfig, DocsRobotsConfig, DocsSearchConfig, DocsSitemapConfig, FeedbackConfig, OrderingItem } from "@farming-labs/docs";
+import { ChangelogConfig, DocsAnalyticsConfig, DocsAskAIMcpConfig, DocsI18nConfig, DocsMcpConfig, DocsObservabilityConfig, DocsRobotsConfig, DocsSearchConfig, DocsSitemapConfig, FeedbackConfig, LlmsTxtConfig, OrderingItem } from "@farming-labs/docs";
 
 //#region src/docs-api.d.ts
 interface AIProviderConfig {
@@ -54,6 +54,8 @@ interface DocsAPIOptions {
   feedback?: boolean | FeedbackConfig;
   /** MCP configuration used for the agent discovery spec. */
   mcp?: boolean | DocsMcpConfig;
+  /** llms.txt configuration. Enabled by default; set false to opt out. */
+  llmsTxt?: boolean | LlmsTxtOptions;
   /** Sitemap configuration used for sitemap.xml and sitemap.md. */
   sitemap?: boolean | DocsSitemapConfig;
   /** Robots.txt generation policy used for the agent discovery spec. */
@@ -72,6 +74,7 @@ interface DocsMCPAPIOptions {
   analytics?: boolean | DocsAnalyticsConfig;
   observability?: boolean | DocsObservabilityConfig;
 }
+type LlmsTxtOptions = LlmsTxtConfig;
 /**
  * Create a unified docs API route handler.
  *

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, createDocsSitemapResponse, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, formatDocsAskAIPackageHints, getDocsMarkdownVaryHeader, hasDocsMarkdownSignatureAgent, normalizeDocsRelated, performDocsSearch, renderDocsMarkdownNotFound, renderDocsRelatedMarkdownLines, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsI18n, resolveDocsLocale, resolveDocsSitemapConfig, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, toDocsMarkdownUrl } from "@farming-labs/docs";
+import { buildDocsAskAIContext, createDocsAgentTraceContext, createDocsAgentTraceId, 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 { createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
@@ -184,6 +184,7 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 	const searchEnabled = isSearchEnabled(search);
 	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: llms.baseUrl });
 	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
+	const llmsSections = resolveDocsLlmsTxtSections(llms);
 	return {
 		version: "1",
 		name: "@farming-labs/docs",
@@ -245,7 +246,14 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			publicTxt: DEFAULT_LLMS_TXT_ROUTE,
 			publicFull: DEFAULT_LLMS_FULL_TXT_ROUTE,
 			wellKnownTxt: DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE,
-			wellKnownFull: DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE
+			wellKnownFull: DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE,
+			...llmsSections.length > 0 ? { sections: llmsSections.map((section) => ({
+				title: section.title,
+				description: section.description,
+				match: section.match,
+				txt: section.route,
+				full: section.fullRoute
+			})) } : {}
 		},
 		sitemap: {
 			enabled: sitemapConfig.enabled,
@@ -927,13 +935,6 @@ function resolveMarkdownRequest(entry, url, request) {
 	}
 	return null;
 }
-function resolveLlmsTxtFormat(url) {
-	const pathname = normalizeUrlPath(url.pathname);
-	if (pathname === DEFAULT_LLMS_TXT_ROUTE || pathname === DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE) return "llms";
-	if (pathname === DEFAULT_LLMS_FULL_TXT_ROUTE || pathname === DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE) return "llms-full";
-	const format = url.searchParams.get("format");
-	return format === "llms" || format === "llms-full" ? format : null;
-}
 function renderMarkdownDocument(page) {
 	if ("agentRawContent" in page && page.agentRawContent !== void 0) return page.agentRawContent;
 	const relatedLines = renderDocsRelatedMarkdownLines(page.related);
@@ -950,6 +951,7 @@ function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitem
 	const searchEnabled = isSearchEnabled(search);
 	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: llms.baseUrl });
 	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
+	const llmsSections = resolveDocsLlmsTxtSections(llms);
 	const lines = [
 		"---",
 		"name: docs",
@@ -963,7 +965,10 @@ function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitem
 	if (siteDescription) lines.push(`Description: ${siteDescription}`);
 	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 (llms.enabled) {
+		lines.push(`- Use ${DEFAULT_LLMS_TXT_ROUTE} for a compact docs index.`, `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} for full markdown context.`);
+		for (const section of llmsSections) lines.push(`- Use ${section.route} for the ${section.title} llms.txt section.`);
+	}
 	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.`);
@@ -973,7 +978,13 @@ function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitem
 	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 (robotsEnabled) lines.push(`- Robots policy: ${DEFAULT_ROBOTS_TXT_ROUTE}`);
-	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 (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}`);
+		for (const section of llmsSections) {
+			lines.push(`- ${section.title} llms.txt: ${section.route}`);
+			lines.push(`- ${section.title} llms-full.txt: ${section.fullRoute}`);
+		}
+	}
 	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}`);
@@ -1495,14 +1506,21 @@ function readLlmsTxtConfig(root) {
 		const configPath = path.join(root, `docs.config.${ext}`);
 		if (fs.existsSync(configPath)) try {
 			const content = fs.readFileSync(configPath, "utf-8");
-			if (!content.includes("llmsTxt")) return { enabled: false };
-			if (/llmsTxt\s*:\s*true/.test(content)) return { enabled: true };
+			const navTitleMatch = content.match(/nav\s*:\s*\{[^}]*title\s*:\s*["']([^"']+)["']/s);
+			if (!content.includes("llmsTxt")) return {
+				enabled: true,
+				siteTitle: navTitleMatch?.[1]
+			};
+			if (/llmsTxt\s*:\s*true/.test(content)) return {
+				enabled: true,
+				siteTitle: navTitleMatch?.[1]
+			};
+			if (/llmsTxt\s*:\s*false/.test(content)) return { enabled: false };
 			const enabledMatch = content.match(/llmsTxt\s*:\s*\{[^}]*enabled\s*:\s*(true|false)/s);
 			if (enabledMatch && enabledMatch[1] === "false") return { enabled: false };
 			const baseUrlMatch = content.match(/llmsTxt\s*:\s*\{[^}]*baseUrl\s*:\s*["']([^"']+)["']/s);
 			const siteTitleMatch = content.match(/llmsTxt\s*:\s*\{[^}]*siteTitle\s*:\s*["']([^"']+)["']/s);
 			const siteDescMatch = content.match(/llmsTxt\s*:\s*\{[^}]*siteDescription\s*:\s*["']([^"']+)["']/s);
-			const navTitleMatch = content.match(/nav\s*:\s*\{[^}]*title\s*:\s*["']([^"']+)["']/s);
 			return {
 				enabled: true,
 				baseUrl: baseUrlMatch?.[1],
@@ -1511,7 +1529,19 @@ function readLlmsTxtConfig(root) {
 			};
 		} catch {}
 	}
-	return { enabled: false };
+	return { enabled: true };
+}
+function resolveLlmsTxtConfig(input, fallback) {
+	if (input === void 0) return fallback;
+	if (typeof input === "boolean") return input ? {
+		...fallback,
+		enabled: true
+	} : { enabled: false };
+	return {
+		...fallback,
+		...input,
+		enabled: input.enabled ?? true
+	};
 }
 function readSitemapConfig(root) {
 	for (const ext of FILE_EXTS) {
@@ -1564,27 +1594,7 @@ function readRobotsConfig(root) {
 	}
 }
 function generateLlmsTxt(indexes, options) {
-	const { siteTitle = "Documentation", siteDescription, baseUrl = "" } = options;
-	let llmsTxt = `# ${siteTitle}\n\n`;
-	if (siteDescription) llmsTxt += `> ${siteDescription}\n\n`;
-	llmsTxt += `## Pages\n\n`;
-	for (const page of indexes) {
-		llmsTxt += `- [${page.title}](${baseUrl}${toDocsMarkdownUrl(page.url)})`;
-		if (page.description) llmsTxt += `: ${page.description}`;
-		llmsTxt += `\n`;
-	}
-	let llmsFullTxt = `# ${siteTitle}\n\n`;
-	if (siteDescription) llmsFullTxt += `> ${siteDescription}\n\n`;
-	for (const page of indexes) {
-		llmsFullTxt += `## ${page.title}\n\n`;
-		llmsFullTxt += `URL: ${baseUrl}${page.url}\n\n`;
-		if (page.description) llmsFullTxt += `${page.description}\n\n`;
-		llmsFullTxt += `${page.content}\n\n---\n\n`;
-	}
-	return {
-		llmsTxt,
-		llmsFullTxt
-	};
+	return renderDocsLlmsTxt(indexes, options);
 }
 /**
 * Create a unified docs API route handler.
@@ -1622,7 +1632,7 @@ function createDocsAPI(options) {
 	const i18n = resolveDocsI18n(options?.i18n ?? readI18nConfig(root));
 	const aiConfig = options?.ai ?? readAIConfig(root);
 	const searchConfig = options?.search;
-	const llmsConfig = readLlmsTxtConfig(root);
+	const llmsConfig = resolveLlmsTxtConfig(options?.llmsTxt, readLlmsTxtConfig(root));
 	const sitemapConfig = options?.sitemap ?? readSitemapConfig(root);
 	const robotsConfig = options?.robots ?? readRobotsConfig(root);
 	const mcpConfig = resolveDocsMcpConfig(options?.mcp ?? readMcpConfig(root), { defaultName: llmsConfig.siteTitle ?? "Documentation" });
@@ -1739,7 +1749,9 @@ function createDocsAPI(options) {
 		const next = generateLlmsTxt(getIndexes(ctx), {
 			siteTitle: llmsConfig.siteTitle ?? "Documentation",
 			siteDescription: llmsConfig.siteDescription,
-			baseUrl: llmsConfig.baseUrl ?? ""
+			baseUrl: llmsConfig.baseUrl ?? "",
+			maxChars: llmsConfig.maxChars,
+			sections: llmsConfig.sections
 		});
 		llmsCacheByLocale.set(key, next);
 		return next;
@@ -1902,31 +1914,45 @@ function createDocsAPI(options) {
 					"X-Robots-Tag": "noindex"
 				} });
 			}
-			const llmsFormat = resolveLlmsTxtFormat(url);
-			if (llmsFormat === "llms") {
-				await emitDocsAnalyticsEvent(analytics, {
-					type: "llms_request",
-					source: "server",
-					url: request.url,
-					path: url.pathname,
-					locale: ctx.locale,
-					properties: { format: "llms" }
+			const llmsRequest = resolveDocsLlmsTxtRequest(url, llmsConfig);
+			if (llmsRequest) {
+				if (!llmsConfig.enabled) return new Response("Not Found", {
+					status: 404,
+					headers: {
+						"Content-Type": "text/plain; charset=utf-8",
+						"X-Robots-Tag": "noindex"
+					}
 				});
-				return new Response(getLlmsContent(ctx).llmsTxt, { headers: {
-					"Content-Type": "text/plain; charset=utf-8",
-					"Cache-Control": "public, max-age=3600"
-				} });
-			}
-			if (llmsFormat === "llms-full") {
+				const selected = selectDocsLlmsTxtContent(getLlmsContent(ctx), llmsRequest);
+				if (!selected) return new Response("Not Found", {
+					status: 404,
+					headers: {
+						"Content-Type": "text/plain; charset=utf-8",
+						"X-Robots-Tag": "noindex"
+					}
+				});
+				const budgetIssue = getDocsLlmsTxtMaxCharsIssue(selected.label, selected.content, selected.maxChars);
+				if (budgetIssue?.mode === "error") return new Response(budgetIssue.message, {
+					status: 500,
+					headers: {
+						"Content-Type": "text/plain; charset=utf-8",
+						"X-Robots-Tag": "noindex"
+					}
+				});
+				if (budgetIssue?.mode === "warn") console.warn(`[docs] ${budgetIssue.message}`);
 				await emitDocsAnalyticsEvent(analytics, {
 					type: "llms_request",
 					source: "server",
 					url: request.url,
 					path: url.pathname,
 					locale: ctx.locale,
-					properties: { format: "llms-full" }
+					properties: {
+						format: llmsRequest.format,
+						section: llmsRequest.section?.route,
+						contentLength: selected.content.length
+					}
 				});
-				return new Response(getLlmsContent(ctx).llmsFullTxt, { headers: {
+				return new Response(selected.content, { headers: {
 					"Content-Type": "text/plain; charset=utf-8",
 					"Cache-Control": "public, max-age=3600"
 				} });

package/dist/docs-layout.mjs

@@ -636,7 +636,7 @@ function createDocsLayout(config, options) {
 	const readingTimeOptions = resolveReadingTimeOptions(config.readingTime);
 	const readingTimeEnabledByDefault = readingTimeOptions.enabled;
 	const readingTimeWordsPerMinute = readingTimeOptions.wordsPerMinute ?? 220;
-	const llmsTxtEnabled = resolveBool(config.llmsTxt);
+	const llmsTxtEnabled = resolveEnabledByDefault(config.llmsTxt);
 	const feedbackConfig = resolveFeedbackConfig(config.feedback);
 	const openDocsProviders = (pageActions?.openDocs && typeof pageActions.openDocs === "object" && pageActions.openDocs.providers ? pageActions.openDocs.providers : void 0)?.map((p) => ({
 		name: p.name,
@@ -795,6 +795,11 @@ function resolveBool(v) {
 	if (typeof v === "boolean") return v;
 	return v.enabled !== false;
 }
+function resolveEnabledByDefault(v) {
+	if (v === void 0) return true;
+	if (typeof v === "boolean") return v;
+	return v.enabled !== false;
+}
 function resolveFeedbackConfig(feedback) {
 	const defaults = {
 		enabled: false,

package/dist/tanstack-layout.mjs

@@ -181,6 +181,11 @@ function resolveBool(value) {
 	if (typeof value === "boolean") return value;
 	return value.enabled !== false;
 }
+function resolveEnabledByDefault(value) {
+	if (value === void 0) return true;
+	if (typeof value === "boolean") return value;
+	return value.enabled !== false;
+}
 function resolveFeedbackConfig(feedback) {
 	const defaults = {
 		enabled: false,
@@ -237,7 +242,7 @@ function TanstackDocsLayout({ config, tree, locale, description, readingTime, la
 	const lastUpdatedEnabled = lastUpdatedRaw !== false && (typeof lastUpdatedRaw !== "object" || lastUpdatedRaw.enabled !== false);
 	const lastUpdatedPosition = typeof lastUpdatedRaw === "object" ? lastUpdatedRaw.position ?? "footer" : "footer";
 	const readingTimeEnabled = resolveReadingTimeOptions(config.readingTime).enabled;
-	const llmsTxtEnabled = resolveBool(config.llmsTxt);
+	const llmsTxtEnabled = resolveEnabledByDefault(config.llmsTxt);
 	const feedbackConfig = resolveFeedbackConfig(config.feedback);
 	const staticExport = !!config.staticExport;
 	const openDocsProviders = (pageActions?.openDocs && typeof pageActions.openDocs === "object" && pageActions.openDocs.providers ? pageActions.openDocs.providers : void 0)?.map((provider) => ({

package/package.json

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