Llms-Text

El plugin @bdocs/plugin-llms-text genera automáticamente un archivo /llms.txt para tu sitio de documentación, siguiendo la especificación llms.txt. Este índice Markdown estandarizado ayuda a los LLMs y agentes de IA a descubrir y entender tu estructura de documentación de manera eficiente — como un robots.txt para asistentes de IA.

Conceptos y Arquitectura

¿Qué es llms.txt?

La especificación llms.txt (propuesta por Jeremy Howard y Answer.AI) define un archivo Markdown estandarizado en texto plano colocado en la raíz de un sitio web que proporciona un índice curado y legible por máquina de las páginas de documentación. A diferencia de las páginas HTML completas (que son pesadas con navegación, JavaScript y marcado), llms.txt es un archivo de texto ligero que los LLMs pueden ingerir eficientemente en su ventana de contexto.

Cómo Funciona

1. Recolección de Rutas: Durante la fase final de generación de assets, el plugin recibe todas las rutas generadas por el pipeline — las mismas rutas usadas para generar las páginas de tu sitio.

2. Agrupación en Secciones: Las rutas se agrupan en secciones H2 basadas en prefijos de ruta. Por defecto:

   • Las rutas de documentación principal van bajo ## Documentation
   • Las rutas de colección (/blog/, /changelog/, /news/) van bajo ## Optional
   • Puedes definir cualquier número de secciones personalizadas

3. Generación de Enlaces: Para cada ruta, el plugin genera un enlace Markdown con el título de la página y una breve descripción (de excerpt o description en el frontmatter):

   text

   - [Título de Página](https://site.com/docs/page): Breve descripción
   

4. Salida: El archivo se escribe en el directorio de compilación como llms.txt, accesible en <siteUrl>/llms.txt.

5. Descubrimiento: El plugin inyecta automáticamente una etiqueta <link rel="llms-txt"> en el <head> de tu HTML, haciendo que el archivo sea descubrible por herramientas automatizadas.

¿Cuándo se Ejecuta?

devMode se conserva por compatibilidad, pero la generación está ligada a la fase de assets de producción. Usa una compilación de producción cuando necesites el archivo en disco.

Configuración

Configuración Mínima

El plugin funciona con configuración cero. Lee automáticamente de tu configuración existente:

Opciones del Plugin

Todas las opciones son opcionales. Pásalas a la función llmsTextPlugin():

llmsTextPlugin({
  title: "Mi Proyecto",
  description: "Un framework de documentación moderno.",
  bodyText: "Patrones clave: React Server Components, Streaming SSR.",
  sortBy: "path",
  sections: [
    { title: "Primeros Pasos", pathPrefix: "/docs/getting-started" },
    { title: "Referencia API", 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",
});

Referencia de API

Referencia de Opciones del Plugin

Opciones de Sección

Cada sección en el arreglo sections tiene las siguientes propiedades:

Archivo Generado

El plugin escribe un único archivo en el directorio de compilación:

Etiqueta HTML Generada

Cuando addLinkTag está activado (por defecto), el plugin inyecta:

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

Esta etiqueta permite que herramientas automatizadas y rastreadores descubran el archivo llms.txt programáticamente.

Ejemplos de Uso

Configuración Básica

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

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

Genera:

# Docs Example

> Documentación completa para Example Project.

## Documentation

- [Instalación](https://docs.example.com/docs/installation): Comienza con la instalación.
- [Configuración](https://docs.example.com/docs/configuration): Configura tu proyecto.
- [Referencia API](https://docs.example.com/docs/api): Documentación completa de la API.

Secciones Personalizadas con Optional

Organiza tu documentación en secciones temáticas:

llmsTextPlugin({
  sections: [
    {
      title: "Primeros Pasos",
      pathPrefix: "/docs/getting-started",
      description: "Guías de inicio rápido y tutoriales.",
    },
    {
      title: "Guías",
      pathPrefix: "/docs/guides",
      description: "Guías detalladas y mejores prácticas.",
    },
    {
      title: "Referencia API",
      pathPrefix: "/docs/api",
    },
    {
      title: "Blog",
      pathPrefix: "/blog/",
      description: "Actualizaciones y anuncios del producto.",
      optional: true,
    },
  ],
});

Incluyendo Instrucciones para LLMs

llmsTextPlugin({
  bodyText: `Este proyecto usa React 19 y Vite 7.

Patrones clave:
- Server Components para obtención de datos
- Streaming SSR para renderizado progresivo
- Tailwind CSS v4 para estilos

Al responder preguntas sobre este proyecto, prefiere el patrón \`use()\`
en lugar de \`useEffect()\` para carga de datos.`,
});

El bodyText aparece después del blockquote y antes de las secciones H2, dándote un área dedicada para instrucciones específicas para LLMs.

Filtrando Rutas

Incluye solo secciones específicas de tu documentación:

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

Seleccionar Idiomas

Cuando tu sitio tiene traducciones, el plugin incluye todos los idiomas por defecto. Usa locales para publicar solo las variantes de idioma que quieres incluir en llms.txt:

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

locales coincide con los códigos configurados en i18n.locales. El idioma por defecto se incluye correctamente aunque sus rutas no tengan un campo locale explícito. Si omites locales, se incluyen todas las rutas traducidas.

Modo de Desarrollo

llmsTextPlugin({
  devMode: true, // opción heredada; la generación ocurre en el build de producción
});

devMode se conserva para no romper configuraciones existentes, pero el archivo no se escribe durante boltdocs dev. En producción, Boltdocs usa build:generate; en versiones antiguas del core se usa automáticamente afterBuild como respaldo.

URL Base Personalizada

llmsTextPlugin({
  baseUrl: "https://docs.example.com", // Sobrescribe siteUrl para los enlaces de llms.txt
});

Límites de Enlaces por Sección

llmsTextPlugin({
  maxLinksPerSection: 20,
  sections: [
    {
      title: "Core",
      pathPrefix: "/docs/core",
      maxLinks: 5, // Sobrescribe el límite global para esta sección
    },
    {
      title: "Extras",
      pathPrefix: "/docs/extras",
      optional: true,
    },
  ],
});

Especificación llms.txt

El archivo generado sigue estrictamente la especificación llms.txt:

# Título del Proyecto

> Resumen conciso del proyecto.

Instrucciones y contexto opcional para LLMs.

## Nombre de Sección

- [Título de Página](https://site.com/ruta): Breve descripción.
- [Otra Página](https://site.com/ruta): Breve descripción.

## Optional

- [Página Suplementaria](https://site.com/ruta): Notas.

Reglas de Estructura

Mejores Prácticas para Contenido Optimizado para LLMs

1. Mantén las descripciones concisas — los LLMs usan las descripciones para decidir si solicitar más contexto. Las descripciones cortas y densas en información ayudan a ahorrar tokens.
2. Usa prefijos de ruta consistentes — agrupa páginas relacionadas para una mejor organización de secciones.
3. Añade instrucciones específicas para LLMs en bodyText — informa a la IA sobre convenciones de código, patrones arquitectónicos o errores comunes.
4. Coloca contenido suplementario bajo Optional — páginas secundarias que pueden omitirse cuando la ventana de contexto es limitada.
5. Usa excerpt en el frontmatter — excerpt tiene prioridad sobre description en la línea del enlace, permitiéndote escribir resúmenes optimizados para LLMs separados de la descripción de tu página.

Control de Posición en el Sidebar

Esta página de documentación aparece en la sección de Plugins del sidebar. Puedes controlar su posición cambiando el valor de sidebarPosition en el frontmatter de este archivo:

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

• Valores más bajos mueven la página hacia arriba en el sidebar (aparece antes)
• Valores más altos la mueven hacia abajo (aparece después)
• La posición por defecto es 999 si no se especifica
• Los empates se resuelven alfabéticamente por título

Si deseas que la página aparezca en una sección diferente, puedes mover este archivo a otro directorio dentro de docs/docs/es/. Por ejemplo, moverlo a docs/docs/es/(guides)/css/llms-text.mdx lo colocaría en la sección de guías CSS en lugar de Plugins.

Solución de Problemas

llms.txt no se genera

• Verifica la versión del core: en versiones actuales se usa build:generate; en cores antiguos el plugin usa afterBuild como respaldo.
• Verifica siteUrl: El plugin requiere que siteUrl esté configurado. Sin él, el plugin registra una advertencia y omite la generación.
• Verifica la compilación: Asegúrate de que la compilación se haya completado con éxito. El plugin escribe durante la fase build:generate, cuando el directorio de salida final ya está resuelto.
• Verifica la ruta de salida: Revisa <raíz-del-proyecto>/dist/llms.txt (o tu directorio de salida configurado). El log incluye llms.txt generated y el tamaño en bytes.
• Verifica el entorno: La generación ocurre durante boltdocs build; el servidor de desarrollo no persiste el archivo en cada request.

La etiqueta link no se inyecta

• Verifica addLinkTag: Asegúrate de no haber establecido addLinkTag: false en las opciones del plugin.
• Verifica siteUrl o baseUrl: La etiqueta link requiere al menos una fuente de URL. Si ninguna está configurada, la etiqueta se omite.

Faltan enlaces en las secciones

• Verifica includePaths/excludePaths: Si estableciste filtros, asegúrate de que tus rutas coincidan con los criterios. excludePaths se aplica después de includePaths.
• Verifica locales: Si configuraste locales, solo se incluyen esos códigos de idioma. Usa exactamente los códigos definidos en i18n.locales (por ejemplo, en, es o pt-BR).
• Verifica maxLinksPerSection: Si tu sección tiene un límite de enlaces, algunas rutas pueden omitirse.
• Verifica los prefijos de ruta: Las rutas deben coincidir con el pathPrefix de al menos una sección para aparecer.

Título o descripción incorrectos

El plugin lee de tu configuración en este orden de prioridad:

Título: options.title → theme.title (localizado) → 'Documentation'

Descripción: options.description → theme.description (localizado) → ''

Si theme.title es un objeto i18n ({ en: 'Docs', es: 'Documentación' }), se usa el primer valor del locale.

Rutas duplicadas entre secciones

Por defecto, el helper buildDefaultSections() coloca las rutas de colección (/blog/, /changelog/, etc.) bajo ## Optional y todo lo demás bajo ## Documentation. Las rutas que coinciden con múltiples prefijos de sección pueden aparecer en múltiples secciones. Para evitar duplicados, define secciones personalizadas con valores de pathPrefix que no se superpongan.

Referencia de Formato de Archivo

Ejemplo Completo de Salida

# Boltdocs

> Un framework de documentación para React/Vite — ligero, rápido y extensible.

Este proyecto usa React 19, Vite 7 y Tailwind CSS v4.

Patrones clave:

- Server Components para obtención de datos
- Streaming SSR para renderizado progresivo

## Formato de Documentación

- [Instalación](https://boltdocs.vercel.app/docs/installation): Comienza con Boltdocs.
- [Configuración](https://boltdocs.vercel.app/docs/configuration): Configura tu proyecto.
- [Referencia API](https://boltdocs.vercel.app/docs/api): Documentación completa de la API.

## Guides

- [Theming](https://boltdocs.vercel.app/docs/guides/theming): Personaliza la apariencia de tu sitio.
- [i18n](https://boltdocs.vercel.app/docs/guides/i18n): Guía de internacionalización.
- [Deployment](https://boltdocs.vercel.app/docs/guides/deployment): Despliega tu documentación.

## Optional (Externo)

- [Anunciando v3](https://boltdocs.vercel.app/blog/v3): Gran actualización con nuevas funciones.
- [Consejos](https://boltdocs.vercel.app/blog/tips): Patrones de uso avanzados.

Jesús Alcalá

Last updated on October 19, 2026