@farming-labs/theme 0.0.2-beta.22 → 0.0.2-beta.23

package/dist/docs-api.d.mts

@@ -38,12 +38,14 @@ interface DocsAPIOptions {
  * Create a unified docs API route handler.
  *
  * Returns `{ GET, POST }` for use in a Next.js route handler:
- * - **GET** → full-text search (same as the old `createDocsSearchAPI`)
- * - **POST** → AI-powered chat with RAG (when AI is enabled in config)
+ * - **GET  ?query=…**        → full-text search
+ * - **GET  ?format=llms**     → llms.txt (concise page listing)
+ * - **GET  ?format=llms-full** → llms-full.txt (full page content)
+ * - **POST**                  → AI-powered chat with RAG
  *
  * @example
  * ```ts
- * // app/api/docs/route.ts
+ * // app/api/docs/route.ts (auto-generated by withDocs)
  * import { createDocsAPI } from "@farming-labs/theme/api";
  * export const { GET, POST } = createDocsAPI();
  * export const revalidate = false;
@@ -53,10 +55,9 @@ interface DocsAPIOptions {
  */
 declare function createDocsAPI(options?: DocsAPIOptions): {
   /**
-   * GET handler — full-text search.
-   * Query: `?query=search+term`
+   * GET handler — search, llms.txt, or llms-full.txt depending on query params.
    */
-  GET: (request: Request) => Promise<Response>;
+  GET(request: Request): Response | Promise<Response>;
   /**
    * POST handler — AI chat with RAG.
    * Body: `{ messages: [{ role: "user", content: "How do I …?" }] }`

package/dist/docs-api.mjs

@@ -163,16 +163,64 @@ async function handleAskAI(request, indexes, searchServer, aiConfig) {
 		Connection: "keep-alive"
 	} });
 }
+function readLlmsTxtConfig(root) {
+	for (const ext of FILE_EXTS) {
+		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 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],
+				siteTitle: siteTitleMatch?.[1] ?? navTitleMatch?.[1],
+				siteDescription: siteDescMatch?.[1]
+			};
+		} catch {}
+	}
+	return { enabled: false };
+}
+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}${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
+	};
+}
 /**
 * Create a unified docs API route handler.
 *
 * Returns `{ GET, POST }` for use in a Next.js route handler:
-* - **GET** → full-text search (same as the old `createDocsSearchAPI`)
-* - **POST** → AI-powered chat with RAG (when AI is enabled in config)
+* - **GET  ?query=…**        → full-text search
+* - **GET  ?format=llms**     → llms.txt (concise page listing)
+* - **GET  ?format=llms-full** → llms-full.txt (full page content)
+* - **POST**                  → AI-powered chat with RAG
 *
 * @example
 * ```ts
-* // app/api/docs/route.ts
+* // app/api/docs/route.ts (auto-generated by withDocs)
 * import { createDocsAPI } from "@farming-labs/theme/api";
 * export const { GET, POST } = createDocsAPI();
 * export const revalidate = false;
@@ -186,13 +234,34 @@ function createDocsAPI(options) {
 	const docsDir = path.join(root, "app", entry);
 	const language = options?.language ?? "english";
 	const aiConfig = options?.ai ?? readAIConfig(root);
+	const llmsConfig = readLlmsTxtConfig(root);
 	const indexes = scanDocsDir(docsDir, entry);
+	let _llmsCache = null;
+	function getLlmsContent() {
+		if (!_llmsCache) _llmsCache = generateLlmsTxt(indexes, {
+			siteTitle: llmsConfig.siteTitle ?? "Documentation",
+			siteDescription: llmsConfig.siteDescription,
+			baseUrl: llmsConfig.baseUrl ?? ""
+		});
+		return _llmsCache;
+	}
 	const searchAPI = createSearchAPI("simple", {
 		language,
 		indexes
 	});
 	return {
-		GET: searchAPI.GET,
+		GET(request) {
+			const format = new URL(request.url).searchParams.get("format");
+			if (format === "llms") return new Response(getLlmsContent().llmsTxt, { headers: {
+				"Content-Type": "text/plain; charset=utf-8",
+				"Cache-Control": "public, max-age=3600"
+			} });
+			if (format === "llms-full") return new Response(getLlmsContent().llmsFullTxt, { headers: {
+				"Content-Type": "text/plain; charset=utf-8",
+				"Cache-Control": "public, max-age=3600"
+			} });
+			return searchAPI.GET(request);
+		},
 		async POST(request) {
 			if (!aiConfig.enabled) return Response.json({ error: "AI is not enabled. Set `ai: { enabled: true }` in your docs.config to enable it." }, { status: 404 });
 			return handleAskAI(request, indexes, searchAPI, aiConfig);

package/dist/docs-layout.mjs

@@ -357,6 +357,7 @@ function createDocsLayout(config) {
 	const lastUpdatedRaw = config.lastUpdated;
 	const lastUpdatedEnabled = lastUpdatedRaw !== false && (typeof lastUpdatedRaw !== "object" || lastUpdatedRaw.enabled !== false);
 	const lastUpdatedPosition = typeof lastUpdatedRaw === "object" ? lastUpdatedRaw.position ?? "footer" : "footer";
+	const llmsTxtEnabled = resolveBool(config.llmsTxt);
 	const openDocsProviders = (typeof pageActions?.openDocs === "object" && pageActions.openDocs.providers ? pageActions.openDocs.providers : void 0)?.map((p) => ({
 		name: p.name,
 		urlTemplate: p.urlTemplate,
@@ -418,6 +419,7 @@ function createDocsLayout(config) {
 					lastModifiedMap,
 					lastUpdatedEnabled,
 					lastUpdatedPosition,
+					llmsTxtEnabled,
 					descriptionMap,
 					children
 				})

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

@@ -33,6 +33,8 @@ interface DocsPageClientProps {
   lastUpdatedEnabled?: boolean;
   /** Where to show the "Last updated" date: "footer" (next to Edit on GitHub) or "below-title" */
   lastUpdatedPosition?: "footer" | "below-title";
+  /** Whether llms.txt is enabled — shows links in footer */
+  llmsTxtEnabled?: boolean;
   /** Map of pathname → frontmatter description */
   descriptionMap?: Record<string, string>;
   /** Frontmatter description to display below the page title (overrides descriptionMap) */
@@ -55,6 +57,7 @@ declare function DocsPageClient({
   lastModifiedMap,
   lastUpdatedEnabled,
   lastUpdatedPosition,
+  llmsTxtEnabled,
   descriptionMap,
   description,
   children

package/dist/docs-page-client.mjs

@@ -63,7 +63,7 @@ function buildGithubFileUrl(githubUrl, branch, pathname, directory) {
 	const segments = pathname.replace(/^\//, "").replace(/\/$/, "");
 	return `${githubUrl}/tree/${branch}/${directory ? `${directory}/` : ""}app/${segments}/page.mdx`;
 }
-function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled = true, entry = "docs", copyMarkdown = false, openDocs = false, openDocsProviders, pageActionsPosition = "below-title", pageActionsAlignment = "left", githubUrl, githubBranch = "main", githubDirectory, lastModifiedMap, lastUpdatedEnabled = true, lastUpdatedPosition = "footer", descriptionMap, description, children }) {
+function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled = true, entry = "docs", copyMarkdown = false, openDocs = false, openDocsProviders, pageActionsPosition = "below-title", pageActionsAlignment = "left", githubUrl, githubBranch = "main", githubDirectory, lastModifiedMap, lastUpdatedEnabled = true, lastUpdatedPosition = "footer", llmsTxtEnabled = false, descriptionMap, description, children }) {
 	const fdTocStyle = tocStyle === "directional" ? "clerk" : void 0;
 	const [toc, setToc] = useState([]);
 	const pathname = usePathname();
@@ -109,7 +109,7 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 	const lastModified = lastUpdatedEnabled ? lastModifiedMap?.[normalizedPath] : void 0;
 	const showLastUpdatedBelowTitle = !!lastModified && lastUpdatedPosition === "below-title";
 	const showLastUpdatedInFooter = !!lastModified && lastUpdatedPosition === "footer";
-	const showFooter = !!githubFileUrl || showLastUpdatedInFooter;
+	const showFooter = !!githubFileUrl || showLastUpdatedInFooter || llmsTxtEnabled;
 	const needsBelowTitleBlock = showLastUpdatedBelowTitle || showActions;
 	useEffect(() => {
 		if (!needsBelowTitleBlock) return;
@@ -188,10 +188,29 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 					children
 				}), showFooter && /* @__PURE__ */ jsxs("div", {
 					className: "not-prose fd-page-footer",
-					children: [githubFileUrl && /* @__PURE__ */ jsx(EditOnGitHub, { href: githubFileUrl }), showLastUpdatedInFooter && lastModified && /* @__PURE__ */ jsxs("span", {
-						className: "fd-last-updated-footer",
-						children: ["Last updated ", lastModified]
-					})]
+					children: [
+						githubFileUrl && /* @__PURE__ */ jsx(EditOnGitHub, { href: githubFileUrl }),
+						llmsTxtEnabled && /* @__PURE__ */ jsxs("span", {
+							className: "fd-llms-txt-links",
+							children: [/* @__PURE__ */ jsx("a", {
+								href: "/api/docs?format=llms",
+								target: "_blank",
+								rel: "noopener noreferrer",
+								className: "fd-llms-txt-link",
+								children: "llms.txt"
+							}), /* @__PURE__ */ jsx("a", {
+								href: "/api/docs?format=llms-full",
+								target: "_blank",
+								rel: "noopener noreferrer",
+								className: "fd-llms-txt-link",
+								children: "llms-full.txt"
+							})]
+						}),
+						showLastUpdatedInFooter && lastModified && /* @__PURE__ */ jsxs("span", {
+							className: "fd-last-updated-footer",
+							children: ["Last updated ", lastModified]
+						})
+					]
 				})]
 			})
 		]

package/dist/search.d.mts

@@ -27,7 +27,7 @@ declare function createDocsSearchAPI(options?: {
   entry?: string;
   language?: string;
 }): {
-  GET: (request: Request) => Promise<Response>;
+  GET(request: Request): Response | Promise<Response>;
   POST(request: Request): Promise<Response>;
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.0.2-beta.22",
+  "version": "0.0.2-beta.23",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -98,7 +98,7 @@
     "next": ">=14.0.0",
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
-    "@farming-labs/docs": "0.0.2-beta.22"
+    "@farming-labs/docs": "0.0.2-beta.23"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",

package/styles/base.css

@@ -409,6 +409,29 @@ figure.shiki:has(figcaption) figcaption {
   margin-left: auto;
 }
 
+.fd-llms-txt-links {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.fd-llms-txt-link {
+  color: var(--color-fd-muted-foreground, hsl(0 0% 45%));
+  font-size: 0.75rem;
+  font-family: var(--fd-font-mono, ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace);
+  text-decoration: none;
+  padding: 0.125rem 0.375rem;
+  border-radius: 0.25rem;
+  border: 1px solid var(--color-fd-border, hsl(0 0% 80% / 50%));
+  transition: color 150ms, border-color 150ms;
+}
+
+.fd-llms-txt-link:hover {
+  /* color: var(--color-fd-foreground, hsl(0 0% 10%));
+  border-color: var(--color-fd-foreground, hsl(0 0% 10%)); */
+  text-decoration: none;
+}
+
 /* ─── Code block copy button: show on hover ────────────────────────── */
 
 figure.shiki > button,

package/styles/pixel-border.css

@@ -425,6 +425,29 @@ figure.shiki > div:first-child {
   font-family: var(--fd-font-mono, var(--font-geist-mono, ui-monospace, monospace));
   text-transform: uppercase;
 }
+/* llms.txt links */
+.fd-llms-txt-links {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.fd-llms-txt-link {
+  color: var(--color-fd-muted-foreground, hsl(0 0% 45%));
+  font-size: 0.65rem !important;
+  font-family: var(--fd-font-mono, ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace);
+  text-decoration: none;
+  padding: 0.015rem 0.4rem !important;
+  border-radius: 0px !important; 
+  border: 0.5px solid var(--color-fd-border, hsl(0 0% 80% / 50%));
+  transition: color 150ms, border-color 150ms;
+}
+
+.fd-llms-txt-link:hover {
+  color: var(--color-fd-foreground, hsl(0 0% 10%)) !important;
+  border: 0.5px solid var(--color-fd-muted-foreground, hsl(0 0% 10% / 10%)) !important;
+  text-decoration: none;
+}
 
 /* ─── Page Actions (pixel-border overrides) ───────────────────────── */