@bdocs/plugin-llms-text 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boltdocs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/node/index.d.mts

@@ -0,0 +1,46 @@
+import { BoltdocsPlugin } from "boltdocs";
+import { z } from "zod";
+
+//#region src/node/schema.d.ts
+/**
+ * Controls which routes are included in the llms.txt.
+ */
+declare const LlmsTextPluginOptionsSchema: z.ZodObject<{
+  title: z.ZodOptional<z.ZodString>;
+  description: z.ZodOptional<z.ZodString>;
+  bodyText: z.ZodOptional<z.ZodString>;
+  includePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  excludePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  locales: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    title: z.ZodString;
+    pathPrefix: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    maxLinks: z.ZodOptional<z.ZodNumber>;
+    optional: z.ZodDefault<z.ZodBoolean>;
+  }, z.core.$strip>>>;
+  sortBy: z.ZodDefault<z.ZodEnum<{
+    title: "title";
+    path: "path";
+    sidebarPosition: "sidebarPosition";
+  }>>;
+  maxLinksPerSection: z.ZodOptional<z.ZodNumber>;
+  includeDrafts: z.ZodDefault<z.ZodBoolean>;
+  devMode: z.ZodDefault<z.ZodBoolean>;
+  addLinkTag: z.ZodDefault<z.ZodBoolean>;
+  baseUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type LlmsTextPluginOptions = z.input<typeof LlmsTextPluginOptionsSchema>;
+//#endregion
+//#region src/node/index.d.ts
+/**
+ * @bdocs/plugin-llms-text — Generate an `llms.txt` file at build time.
+ *
+ * The llms.txt specification (llmstxt.org) provides a standardised
+ * plain-text index of documentation pages optimised for Large Language
+ * Models and AI agents. The file is emitted into the resolved build output
+ * directory and is therefore served at `<siteUrl>/llms.txt`.
+ */
+declare function llmsTextPlugin(rawOptions?: LlmsTextPluginOptions): BoltdocsPlugin;
+//#endregion
+export { type LlmsTextPluginOptions, llmsTextPlugin as default };

package/dist/node/index.mjs

@@ -0,0 +1,359 @@
+import { createPlugin } from "boltdocs";
+import { z } from "zod";
+import path from "node:path";
+import fs from "node:fs";
+//#region src/node/schema.ts
+/**
+* Configuration for a custom section in the llms.txt file.
+* Each section maps to an H2 heading with a list of curated links.
+*/
+const LlmsTextSectionSchema = z.object({
+	/** The H2 heading label for this section (e.g. 'Getting Started'). */
+	title: z.string().min(1).max(100),
+	/** Path prefix filter — only routes starting with this path are included. */
+	pathPrefix: z.string().min(1).max(200),
+	/** Optional description paragraph placed right after the H2 heading. */
+	description: z.string().max(500).optional(),
+	/** Maximum links in this section. Default: no limit. */
+	maxLinks: z.number().int().positive().max(500).optional(),
+	/** Whether this section should appear under the '## Optional' umbrella. */
+	optional: z.boolean().default(false)
+});
+/**
+* Controls link sorting within each section.
+*/
+const SortBySchema = z.enum([
+	"path",
+	"title",
+	"sidebarPosition"
+]).default("sidebarPosition");
+/**
+* Controls which routes are included in the llms.txt.
+*/
+const LlmsTextPluginOptionsSchema = z.object({
+	/**
+	* Project title used as the H1 heading.
+	* Defaults to the site title from boltdocs config.
+	*/
+	title: z.string().min(1).max(200).optional(),
+	/**
+	* Project description used as the blockquote summary.
+	* Defaults to the site description from boltdocs config.
+	*/
+	description: z.string().min(1).max(1e3).optional(),
+	/**
+	* Additional markdown body text inserted after the blockquote
+	* and before any H2 sections. Use this for LLM-specific instructions,
+	* common patterns, or high-level architecture notes.
+	*/
+	bodyText: z.string().max(2e3).optional(),
+	/**
+	* If set, only routes matching at least one of these path prefixes
+	* are included. Example: ['/docs', '/blog']. Default: all routes.
+	*/
+	includePaths: z.array(z.string()).optional(),
+	/**
+	* Routes matching any of these path prefixes are excluded.
+	* Applied AFTER includePaths. Example: ['/docs/api/experimental'].
+	*/
+	excludePaths: z.array(z.string()).optional(),
+	/**
+	* Restrict links to the selected locale codes. The default locale is
+	* matched automatically even when its RouteMeta.locale is undefined.
+	* Example: ['en', 'es']. When omitted, all locales are included.
+	*/
+	locales: z.array(z.string().trim().min(1)).optional(),
+	/**
+	* Custom H2 sections that group links by path prefix.
+	* When provided, the default "Documentation" section is replaced.
+	* Default: a single "Documentation" section with all routes.
+	*/
+	sections: z.array(LlmsTextSectionSchema).optional(),
+	/**
+	* How to sort links within each section.
+	*/
+	sortBy: SortBySchema,
+	/**
+	* Maximum number of links per section. Default: no limit.
+	*/
+	maxLinksPerSection: z.number().int().positive().max(500).optional(),
+	/**
+	* Whether to include draft routes. Default: false.
+	*/
+	includeDrafts: z.boolean().default(false),
+	/**
+	* @deprecated The afterBuild hook is always registered now; generation
+	* happens on every production build. This option is kept for backwards
+	* compatibility and no longer has any effect.
+	*/
+	devMode: z.boolean().default(false),
+	/**
+	* Whether to inject a `<link rel="llms-txt">` tag into the HTML `<head>`.
+	* Default: true.
+	*/
+	addLinkTag: z.boolean().default(true),
+	/**
+	* URL base for generating absolute links in llms.txt.
+	* Falls back to `siteUrl` from the boltdocs config.
+	*/
+	baseUrl: z.string().url().optional()
+});
+//#endregion
+//#region src/node/generator.ts
+/**
+* Sort routes within a section according to the configured sort order.
+*/
+function sortRoutes(routes, sortBy) {
+	const sorted = [...routes];
+	switch (sortBy) {
+		case "path":
+			sorted.sort((a, b) => a.path.localeCompare(b.path));
+			break;
+		case "title":
+			sorted.sort((a, b) => a.title.localeCompare(b.title));
+			break;
+		case "sidebarPosition":
+			sorted.sort((a, b) => {
+				const aPos = a.sidebarPosition ?? 999;
+				const bPos = b.sidebarPosition ?? 999;
+				if (aPos !== bPos) return aPos - bPos;
+				return a.title.localeCompare(b.title);
+			});
+			break;
+	}
+	return sorted;
+}
+/**
+* Format a single link line following the llms.txt spec:
+* `- [Page Title](https://site.com/docs/page): Brief description`
+*/
+function formatLink(route, siteUrl) {
+	const url = `${siteUrl.replace(/\/+$/, "")}${route.path}`;
+	const description = route.excerpt ?? route.description ?? "";
+	const label = description ? `: ${description.replace(/\n/g, " ").replace(/\s+/g, " ").trim()}` : "";
+	return `- [${escapeLinkText(route.title)}](${url})${label}`;
+}
+/**
+* Escape special characters in plain-text Markdown link text.
+* Square brackets would break the `[text]` syntax, and parentheses
+* would break the `(url)` syntax.
+*/
+function escapeLinkText(text) {
+	return text.replace(/\[/g, "\\[").replace(/\]/g, "\\]").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+}
+/**
+* Check a single route against include/exclude path filters.
+* Returns `true` when the route passes all filters.
+*/
+function routePassesPathFilter(route, config) {
+	if (config.locales && config.locales.length > 0) {
+		const routeLocale = route.locale ?? config.defaultLocale;
+		if (routeLocale && !config.locales.includes(routeLocale)) return false;
+	}
+	if (config.includePaths && config.includePaths.length > 0) {
+		if (!config.includePaths.some((p) => route.path.startsWith(p))) return false;
+	}
+	if (config.excludePaths && config.excludePaths.length > 0) {
+		if (config.excludePaths.some((p) => route.path.startsWith(p))) return false;
+	}
+	return true;
+}
+/**
+* Group routes into a single section based on path prefix matching.
+*/
+function routesForSection(routes, section, config, skipSort = false) {
+	const filtered = routes.filter((r) => {
+		if (!config.includeDrafts && r.draft) return false;
+		if (!routePassesPathFilter(r, config)) return false;
+		return r.path.startsWith(section.pathPrefix);
+	});
+	const result = skipSort ? filtered : sortRoutes(filtered, config.sortBy);
+	const maxLinks = section.maxLinks ?? config.maxLinksPerSection;
+	if (maxLinks && result.length > maxLinks) return result.slice(0, maxLinks);
+	return result;
+}
+/**
+* Generate the full llms.txt Markdown content.
+*
+* Follows the llms.txt specification:
+* 1. H1 - Project title
+* 2. Blockquote - Summary/short description
+* 3. Optional body text
+* 4. H2 sections with curated links
+* 5. Optional sections under `## Optional`
+*/
+function generateLlmsText(routes, config) {
+	const lines = [];
+	lines.push(`# ${config.title}`);
+	lines.push("");
+	lines.push(`> ${config.description}`);
+	lines.push("");
+	if (config.bodyText) {
+		lines.push(config.bodyText.trim());
+		lines.push("");
+	}
+	const requiredSections = config.sections.filter((s) => !s.optional);
+	const optionalSections = config.sections.filter((s) => s.optional);
+	for (const section of requiredSections) {
+		const sectionRoutes = routesForSection(routes, section, config);
+		if (sectionRoutes.length === 0) continue;
+		lines.push(`## ${section.title}`);
+		if (section.description) {
+			lines.push("");
+			lines.push(section.description);
+		}
+		lines.push("");
+		for (const route of sectionRoutes) lines.push(formatLink(route, config.siteUrl));
+		lines.push("");
+	}
+	if (optionalSections.length > 0) {
+		const allOptionalRoutes = [];
+		for (const section of optionalSections) {
+			const sectionRoutes = routesForSection(routes, section, config, true);
+			allOptionalRoutes.push(...sectionRoutes);
+		}
+		if (allOptionalRoutes.length > 0) {
+			const sorted = sortRoutes(allOptionalRoutes, config.sortBy);
+			lines.push("## Optional");
+			lines.push("");
+			for (const route of sorted) lines.push(formatLink(route, config.siteUrl));
+			lines.push("");
+		}
+	}
+	return lines.join("\n").trim() + "\n";
+}
+/**
+* Build the default sections from available routes when the user
+* has not provided custom sections.
+*/
+function buildDefaultSections(routes) {
+	const sections = [];
+	const collectionPrefixes = /* @__PURE__ */ new Set();
+	for (const route of routes) {
+		if (route.draft) continue;
+		const parts = route.path.split("/").filter(Boolean);
+		if (parts.length > 1) {
+			const prefix = "/" + parts[0] + "/";
+			if ([
+				"/blog/",
+				"/changelog/",
+				"/news/",
+				"/release-notes/"
+			].some((p) => prefix.startsWith(p))) collectionPrefixes.add(prefix);
+		}
+	}
+	if (routes.filter((r) => {
+		if (r.draft) return false;
+		if (r.path.split("/").filter(Boolean).length <= 1) return true;
+		for (const cp of collectionPrefixes) if (r.path.startsWith(cp)) return false;
+		return true;
+	}).length > 0) sections.push({
+		title: "Documentation",
+		pathPrefix: "/",
+		description: "Core documentation pages covering installation, usage, API reference, and guides.",
+		optional: false
+	});
+	for (const prefix of collectionPrefixes) {
+		const label = prefix.replace(/^\//, "").replace(/\/$/, "").split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+		sections.push({
+			title: label,
+			pathPrefix: prefix,
+			description: `${label} articles and posts.`,
+			optional: true
+		});
+	}
+	return sections;
+}
+/**
+* Write the generated llms.txt to disk.
+*/
+function writeLlmsText(content, outDir, logger) {
+	const outputPath = path.join(outDir, "llms.txt");
+	fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+	fs.writeFileSync(outputPath, content, "utf-8");
+	logger(`llms.txt generated: llms.txt (${Buffer.byteLength(content, "utf-8")} bytes)`);
+}
+/**
+* Format the site URL — strip trailing slash for consistency.
+*/
+function formatSiteUrl(raw) {
+	return raw.replace(/\/+$/, "");
+}
+//#endregion
+//#region src/node/index.ts
+/**
+* @bdocs/plugin-llms-text — Generate an `llms.txt` file at build time.
+*
+* The llms.txt specification (llmstxt.org) provides a standardised
+* plain-text index of documentation pages optimised for Large Language
+* Models and AI agents. The file is emitted into the resolved build output
+* directory and is therefore served at `<siteUrl>/llms.txt`.
+*/
+function llmsTextPlugin(rawOptions = {}) {
+	const options = LlmsTextPluginOptionsSchema.parse(rawOptions);
+	function linkTagInjection(ctx, params) {
+		if (!options.addLinkTag) return { html: params.html };
+		const siteUrl = ctx.config.siteUrl ?? options.baseUrl;
+		if (!siteUrl) return { html: params.html };
+		const tag = `<link rel="llms-txt" href="${formatSiteUrl(siteUrl)}/llms.txt"/>\n</head>`;
+		return { html: params.html.replace("</head>", tag) };
+	}
+	function resolveConfig(ctx) {
+		const siteUrl = options.baseUrl ?? ctx.config.siteUrl;
+		if (!siteUrl) {
+			ctx.logger.info("[llms-text] Skipping generation: no siteUrl configured. Set siteUrl in boltdocs.config.ts or pass baseUrl to the plugin.");
+			return null;
+		}
+		const themeTitle = ctx.config.theme?.title;
+		const title = options.title ?? (typeof themeTitle === "object" && themeTitle !== null ? Object.values(themeTitle)[0] : themeTitle) ?? "Documentation";
+		const themeDescription = ctx.config.theme?.description;
+		const description = options.description ?? (typeof themeDescription === "object" && themeDescription !== null ? Object.values(themeDescription)[0] : themeDescription) ?? "";
+		const sections = options.sections ?? buildDefaultSections(ctx.routes);
+		return {
+			title,
+			description,
+			bodyText: options.bodyText,
+			siteUrl: formatSiteUrl(siteUrl),
+			sections,
+			sortBy: options.sortBy,
+			maxLinksPerSection: options.maxLinksPerSection,
+			includeDrafts: options.includeDrafts,
+			includePaths: options.includePaths,
+			excludePaths: options.excludePaths,
+			locales: options.locales,
+			defaultLocale: ctx.config.i18n?.defaultLocale
+		};
+	}
+	let generatedKey = null;
+	const generate = (ctx, routes, outputDir) => {
+		const resolved = resolveConfig({
+			...ctx,
+			routes
+		});
+		if (!resolved) return;
+		const content = generateLlmsText(routes, resolved);
+		const normalizedOutputDir = path.resolve(outputDir);
+		const key = `${normalizedOutputDir}\0${content}`;
+		if (generatedKey === key) return;
+		writeLlmsText(content, normalizedOutputDir, ctx.logger.info);
+		generatedKey = key;
+	};
+	return createPlugin({
+		name: "boltdocs-plugin-llms-text",
+		version: "0.1.0",
+		hooks: {
+			async "build:generate"(ctx, params) {
+				generate(ctx, params.routes, params.outDir);
+			},
+			async afterBuild(ctx) {
+				const outputDir = path.resolve(ctx.rootDir ?? process.cwd(), ctx.outDir);
+				generate(ctx, ctx.routes, outputDir);
+			},
+			transformHtml(ctx, params) {
+				return linkTagInjection(ctx, params);
+			}
+		}
+	});
+}
+//#endregion
+export { llmsTextPlugin as default };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@bdocs/plugin-llms-text",
+  "version": "0.2.0",
+  "description": "llms.txt generator plugin for Boltdocs — provides AI-optimized documentation indexes for LLMs and AI agents",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/node/index.d.mts",
+      "import": "./dist/node/index.mjs"
+    }
+  },
+  "author": "Jesus Alcala",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "boltdocs": "^3.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsdown": "^0.21.7",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "boltdocs": "^3.3.0",
+    "tsdown-config": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsdown --config-loader unrun",
+    "dev": "tsdown --watch --config-loader unrun",
+    "test": "vitest run"
+  }
+}