Llms-Text

The @bdocs/plugin-llms-text plugin automatically generates a /llms.txt file for your documentation site, following the llms.txt specification. This standardised Markdown index helps LLMs and AI agents discover and understand your documentation structure efficiently — like a robots.txt for AI assistants.

Concepts & Architecture

What is llms.txt?

The llms.txt specification (proposed by Jeremy Howard and Answer.AI) defines a standardised plain-text Markdown file placed at the root of a website that provides a curated, machine-readable index of documentation pages. Unlike full HTML pages (which are heavy with navigation, JavaScript, and markup), llms.txt is a lightweight text file that LLMs can efficiently ingest into their context window.

How It Works

1. Route Collection: During the final asset-generation phase, the plugin receives all generated routes from the build pipeline — the same routes used to generate your site's pages.

2. Section Grouping: Routes are grouped into H2 sections based on path prefixes. By default:

   • Core documentation routes go under ## Documentation
   • Collection routes (/blog/, /changelog/, /news/) go under ## Optional
   • You can define any number of custom sections

3. Link Generation: For each route, the plugin generates a Markdown link with the page title and a brief description (from excerpt or description frontmatter):

   text

   - [Page Title](https://site.com/docs/page): Brief description
   

4. Output: The file is written to the build output directory as llms.txt, accessible at <siteUrl>/llms.txt.

5. Discovery: The plugin automatically injects a <link rel="llms-txt"> tag into your HTML <head>, making the file discoverable by automated tools.

When Does It Run?

devMode is retained for backwards compatibility, but generation is tied to the production asset phase. Use a production build when you need a file on disk.

Configuration

Minimal Setup

The plugin works with zero configuration. It automatically reads from your existing config:

Plugin Options

All options are optional. Pass them to the llmsTextPlugin() factory function:

llmsTextPlugin({
  title: "My Project",
  description: "A modern documentation framework.",
  bodyText: "Key patterns: React Server Components, Streaming SSR.",
  sortBy: "path",
  sections: [
    { title: "Getting Started", pathPrefix: "/docs/getting-started" },
    { title: "API Reference", pathPrefix: "/docs/api", optional: true },
  ],
  includePaths: ["/docs", "/blog"],
  excludePaths: ["/blog/experimental"],
  locales: ["en", "es"],
  maxLinksPerSection: 50,
  includeDrafts: false,
  devMode: false,
  addLinkTag: true,
  baseUrl: "https://custom-domain.com",
});

API Reference

Plugin Options Reference

Section Options

Each section in the sections array has the following properties:

Generated File

The plugin writes a single file to the build output directory:

Generated HTML Tag

When addLinkTag is enabled (default), the plugin injects:

<link rel="llms-txt" href="https://my-docs.com/llms.txt" />

This tag allows automated tools and crawlers to discover the llms.txt file programmatically.

Usage Examples

Basic Setup

import { defineConfig } from "boltdocs";
import llmsTextPlugin from "@bdocs/plugin-llms-text";

export default defineConfig({
  siteUrl: "https://docs.example.com",
  plugins: [llmsTextPlugin()],
});

Generates:

# Docs Example

> Comprehensive documentation for Example Project.

## Documentation

- [Installation](https://docs.example.com/docs/installation): Get started with installation.
- [Configuration](https://docs.example.com/docs/configuration): Configure your project.
- [API Reference](https://docs.example.com/docs/api): Complete API documentation.

Custom Sections with Optional

Organise your documentation into themed sections:

llmsTextPlugin({
  sections: [
    {
      title: "Getting Started",
      pathPrefix: "/docs/getting-started",
      description: "Quick start guides and tutorials.",
    },
    {
      title: "Guides",
      pathPrefix: "/docs/guides",
      description: "In-depth guides and best practices.",
    },
    {
      title: "API Reference",
      pathPrefix: "/docs/api",
    },
    {
      title: "Blog",
      pathPrefix: "/blog/",
      description: "Product updates and announcements.",
      optional: true,
    },
  ],
});

Including LLM Instructions

llmsTextPlugin({
  bodyText: `This project uses React 19 and Vite 7.

Key patterns:
- Server Components for data fetching
- Streaming SSR for progressive rendering
- Tailwind CSS v4 for styling

When answering questions about this project, prefer the `use()` hook pattern
over `useEffect()` for data loading.`,
})

The bodyText appears after the blockquote and before the H2 sections, giving you a dedicated area for LLM-specific guidance.

Filtering Routes

Only include specific sections of your docs:

llmsTextPlugin({
  includePaths: ["/docs", "/guides"],
  excludePaths: ["/docs/experimental", "/guides/legacy"],
});

Selecting Locales

When your site has translations, the plugin includes every locale by default. Use locales to publish only the language variants you want in llms.txt:

llmsTextPlugin({
  locales: ["en", "es"],
});

locales matches the locale codes from i18n.locales. The default locale is included correctly even when its routes have no explicit locale field. If locales is omitted, all localized routes are included.

Development Mode

llmsTextPlugin({
  devMode: true, // legacy compatibility option; generated on production build
});

devMode remains accepted so existing configurations keep working, but the file is not written during boltdocs dev. Current cores use build:generate; older cores are handled automatically through an afterBuild fallback.

Custom Base URL

llmsTextPlugin({
  baseUrl: "https://docs.example.com", // Overrides siteUrl for llms.txt links
});

Per-Section Link Limits

llmsTextPlugin({
  maxLinksPerSection: 20,
  sections: [
    {
      title: "Core",
      pathPrefix: "/docs/core",
      maxLinks: 5, // Overrides global limit for this section
    },
    {
      title: "Extras",
      pathPrefix: "/docs/extras",
      optional: true,
    },
  ],
});

llms.txt Specification

The generated file follows the llms.txt specification strictly:

# Project Title

> Concise project summary.

Optional LLM instructions and context.

## Section Name

- [Page Title](https://site.com/path): Brief description.
- [Another Page](https://site.com/path): Brief description.

## Optional

- [Supplementary Page](https://site.com/path): Notes.

Structure Rules

Best Practices for LLM-Optimised Content

1. Keep descriptions concise — LLMs use descriptions to decide whether to request more context. Short, information-dense descriptions help save tokens.
2. Use consistent path prefixes — group related pages together for better section organisation.
3. Add LLM-specific instructions in bodyText — tell the AI about coding conventions, architectural patterns, or common gotchas.
4. Place supplementary content under Optional — secondary pages that can be skipped when the context window is tight.
5. Use excerpt frontmatter — excerpt takes priority over description in the link line, letting you write LLM-optimised summaries separate from your page description.

Controlling Sidebar Position

This documentation page appears in the Plugins section of the sidebar. You can control its position by changing the sidebarPosition value in the frontmatter of this file:

---
title: "@bdocs/plugin-llms-text"
sidebarPosition: 7
---

• Lower values move the page up in the sidebar (appears earlier)
• Higher values move it down (appears later)
• Default position is 999 if not specified
• Ties are broken alphabetically by title

If you want the page to appear in a different section entirely, you can move this file to another directory under docs/docs/. For example, moving it to docs/docs/(guides)/css/llms-text.mdx would place it under the CSS guides section instead of Plugins.

Troubleshooting

llms.txt not generated

• Check the core version: current cores use build:generate; older cores are handled by the plugin's afterBuild fallback.
• Check siteUrl: The plugin requires siteUrl to be set in your config. Without it, the plugin logs a warning and skips generation.
• Verify build output: Ensure the build completed successfully. The plugin writes during the build:generate asset phase, after the final output directory is resolved.
• Check the output path: Inspect <project-root>/dist/llms.txt (or your configured output directory). The build log includes llms.txt generated and its byte size.
• Check environment: Generation happens during boltdocs build; the dev server does not persist the file on every request.

Link tag not injected

• Check addLinkTag: Ensure you haven't set addLinkTag: false in the plugin options.
• Check siteUrl or baseUrl: The link tag requires at least one URL source. If neither is set, the tag is skipped.

Links missing from sections

• Check includePaths/excludePaths: If you set filters, ensure your routes match the criteria. excludePaths is applied after includePaths.
• Check locales: If you set locales, only those locale codes are included. Use the exact codes configured in i18n.locales (for example, en, es, or pt-BR).
• Check maxLinksPerSection: If your section has a link limit, some routes may be omitted.
• Check route prefixes: Routes must match the pathPrefix of at least one section to appear.

Wrong title or description

The plugin reads from your config in this priority order:

Title: options.title → theme.title (localized) → 'Documentation'

Description: options.description → theme.description (localized) → ''

If theme.title is an i18n object ({ en: 'Docs', es: 'Documentación' }), the first locale value is used.

Duplicate routes across sections

By default, the buildDefaultSections() helper places collection routes (/blog/, /changelog/, etc.) under ## Optional and everything else under ## Documentation. Routes that match multiple section prefixes may appear in multiple sections. To avoid duplicates, define custom sections with non-overlapping pathPrefix values.

File Format Reference

Full Example Output

# Boltdocs

> A React/Vite documentation framework — lightweight, fast, and extensible.

This project uses React 19, Vite 7, and Tailwind CSS v4.

Key patterns:

- Server Components for data fetching
- Streaming SSR for progressive rendering

## Documentation Format

- [Installation](https://boltdocs.vercel.app/docs/installation): Get started with Boltdocs.
- [Configuration](https://boltdocs.vercel.app/docs/configuration): Configure your project.
- [API Reference](https://boltdocs.vercel.app/docs/api): Complete API documentation.

## Guides

- [Theming](https://boltdocs.vercel.app/docs/guides/theming): Customise your site appearance.
- [i18n](https://boltdocs.vercel.app/docs/guides/i18n): Internationalisation guide.
- [Deployment](https://boltdocs.vercel.app/docs/guides/deployment): Deploy your docs.

## Optional (External)

- [Announcing v3](https://boltdocs.vercel.app/blog/v3): Major update with new features.
- [Pro Tips](https://boltdocs.vercel.app/blog/tips): Advanced usage patterns.

Jesús Alcalá

Last updated on October 19, 2026