@farming-labs/theme 0.1.88 → 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 {
@@ -74,12 +74,7 @@ interface DocsMCPAPIOptions {
   analytics?: boolean | DocsAnalyticsConfig;
   observability?: boolean | DocsObservabilityConfig;
 }
-interface LlmsTxtOptions {
-  enabled?: boolean;
-  siteTitle?: string;
-  siteDescription?: string;
-  baseUrl?: string;
-}
+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}`);
@@ -1583,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.
@@ -1758,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;
@@ -1921,8 +1914,8 @@ function createDocsAPI(options) {
 					"X-Robots-Tag": "noindex"
 				} });
 			}
-			const llmsFormat = resolveLlmsTxtFormat(url);
-			if (llmsFormat === "llms" || llmsFormat === "llms-full") {
+			const llmsRequest = resolveDocsLlmsTxtRequest(url, llmsConfig);
+			if (llmsRequest) {
 				if (!llmsConfig.enabled) return new Response("Not Found", {
 					status: 404,
 					headers: {
@@ -1930,31 +1923,36 @@ function createDocsAPI(options) {
 						"X-Robots-Tag": "noindex"
 					}
 				});
-			}
-			if (llmsFormat === "llms") {
-				await emitDocsAnalyticsEvent(analytics, {
-					type: "llms_request",
-					source: "server",
-					url: request.url,
-					path: url.pathname,
-					locale: ctx.locale,
-					properties: { format: "llms" }
+				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"
+					}
 				});
-				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 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/package.json

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