Configuración

Un recorrido guiado por cada clave de nivel superior en boltdocs.config.ts y los problemas reales que cada una resuelve.

boltdocs.config.ts es el único archivo de configuración para todo tu sitio de documentación. Vive en la raíz de tu proyecto junto a package.json y controla todo, desde el título del sitio hasta el stack de plugins y el comportamiento de SEO.

boltdocs.config.ts

import { defineConfig } from 'boltdocs'

export default defineConfig({
  siteUrl: 'https://my-project.com',
  base: '/docs',
  theme: {
    title: 'My Project',
    githubRepo: 'my-org/my-project',
  },
})

Boltdocs lee este archivo al iniciar y genera una configuración completa de Vite internamente. Nunca necesitas tocar un vite.config.ts.

Agrega aliases propios del proyecto sin reemplazar los aliases internos que usa Boltdocs:

boltdocs.config.ts

export default defineConfig({
  aliases: {
    '@components': './src/components',
    '@data': './src/data',
  },
})

El core mantiene configurados automáticamente aliases como boltdocs/client, boltdocs/entry y use-sync-external-store. La opción aliases acepta los mismos formatos de objeto o array que Vite. Las configuraciones avanzadas de Vite todavía pueden definirse mediante vite; vite.resolve.alias se fusiona con aliases en lugar de reemplazar los aliases del framework. Los aliases del framework tienen prioridad si el mismo alias se declara dos veces.

Controla toda la shell visual de tu sitio de documentación.

Propiedad	Tipo	Por Defecto	Descripción
`title`	`string \| Record<string, string>`	`'Boltdocs'`	El título principal mostrado en la navbar y pestañas del navegador. Soporta mapas de claves de locale para i18n.
`description`	`string`	—	Una descripción corta usada en meta tags de SEO por defecto.
`logo`	`LogoConfig`	`undefined`	Imágenes de logo personalizadas para modos claro y oscuro.
`favicon`	`string`	—	Ruta al favicon (relativa a `public/`).
`githubRepo`	`string`	—	Repositorio en formato `owner/repo`. Habilita el enlace de GitHub en la navbar automáticamente.
`navbar`	`NavbarItem[]`	—	Enlaces de navegación de nivel superior. Soporta elementos anidados con dropdown.
`tabs`	`TabConfig[]`	—	Franja de pestañas horizontal sobre el sidebar. Consulta Enrutamiento por Sistema de Archivos.
`sidebar`	`SidebarConfig`	—	Estructura del sidebar definida manualmente (deshabilita el auto-descubrimiento para esos prefijos).
`sidebarGroups`	`Record<string, SidebarGroupConfig>`	—	Sobreescribe títulos e iconos de grupos sin definir un sidebar manual completo.
`codeTheme`	`CodeThemeConfig`	—	Configura el tema del resaltado de código. Obsoleto — usa `codeHighlighting`. Acepta los mismos valores que `codeHighlighting.theme`.
`codeHighlighting`	`CodeHighlightConfig`	—	Motor y tema del resaltado de código. Agnóstico al motor: usa el motor Shiki por defecto y acepta cualquier `CodeHighlighterAdapter` personalizado.
`editLink`	`string`	—	Plantilla de URL para el enlace "Editar esta página". Usa `:path` como placeholder para la ruta relativa del archivo actual.
`socialLinks`	`SocialLink[]`	—	Enlaces de iconos extra (Twitter/X, Discord, etc.) mostrados en la navbar.
`communityHelp`	`string`	—	Enlace de soporte (por ejemplo, URL de Discord, Slack o foro) mostrado en el pie de página.
`version`	`string`	—	Cadena de versión del release mostrada en la navbar.

Propiedad	Tipo	Por Defecto	Descripción
`dark`	`string`	—	Ruta a la imagen del logo mostrada en modo oscuro (relativa a `public/`).
`light`	`string`	—	Ruta a la imagen del logo mostrada en modo claro.
`alt`	`string`	Título	Texto alternativo para el `<img>` del logo.
`width`	`number`	—	Ancho explícito en píxeles para la imagen del logo.
`height`	`number`	—	Alto explícito en píxeles para la imagen del logo.

Propiedad	Tipo	Por Defecto	Descripción
`light`	`string`	`'github-light'`	Nombre del tema de Shiki para modo claro.
`dark`	`string`	`'github-dark'`	Nombre del tema de Shiki para modo oscuro.

Temas disponibles: github-light, github-dark, tokyo-night, dracula, nord, one-dark-pro, one-light.

La forma agnóstica al motor de configurar el resaltado de código. El core nunca habla directamente con una librería de resaltado — renderiza a través de un CodeHighlighterAdapter resuelto desde un registry, así que Shiki es solo el motor por defecto y cualquier resaltador se puede conectar sin tocar el core.

Propiedad	Tipo	Por Defecto	Descripción
`engine`	`string \| CodeHighlighterAdapter \| (api) => CodeHighlighterAdapter`	`'shiki'`	El motor de resaltado. Un string es un id del registry (`'shiki'` o cualquier motor registrado por un plugin). Pasa una instancia de adapter o una factoría para inyectar un motor personalizado.
`theme`	`string \| { light; dark }`	`{ light: 'github-light', dark: 'github-dark' }`	Nombre de tema o par claro/oscuro. Con un objeto, los bloques renderizados llevan `data-theme-mode="dual"` y usan las variables CSS `--shiki-light`/`--shiki-dark`.
`options`	`Record<string, unknown>`	`{}`	Opciones específicas del motor, pasadas al adapter.

Opciones para el motor Shiki integrado:

Opción	Tipo	Por Defecto	Descripción
`regexEngine`	`'oniguruma' \| 'javascript'`	`'oniguruma'`	`'javascript'` reemplaza el WASM de Oniguruma por el motor de regex nativo JS de Shiki, reduciendo el arranque del resaltador de ~2.5s a ~200ms a costa de algo de fidelidad en gramáticas exóticas. Útil para arranques de dev-server más rápidos.

export default defineConfig({
  theme: {
    codeHighlighting: {
      engine: 'shiki',
      theme: {
        light: 'github-light',
        dark: 'github-dark',
      },
      options: {
        regexEngine: 'javascript',
      },
    },
  },
})

Los plugins exponen un motor a través del campo codeHighlighter. El adapter se registra bajo el nombre del plugin, así que engine puede seleccionarlo por id:

import { defineConfig, definePlugin, type CodeHighlighterAdapter } from 'boltdocs'

const prismEngine: CodeHighlighterAdapter = {
  name: 'prism',
  getOptions(lang, meta) {
    return { lang, theme: 'one-light' }
  },
  async initialize() {
    const prism = await import('your-prism-wrapper')
    return {
      codeToHast: (code, options) => prism.toHast(code, options),
      codeToHtml: async (code, options) => prism.toHtml(code, options),
    }
  },
  async ensureLanguage(lang) {
    return true
  },
}

const prismPlugin = definePlugin({
  name: 'my-prism',
  codeHighlighter: prismEngine,
})

export default defineConfig({
  plugins: [prismPlugin()],
  theme: {
    codeHighlighting: { engine: 'my-prism' },
  },
})

También se puede pasar un motor inline como instancia de adapter o factoría sin registrar un plugin:

codeHighlighting: {
  engine: {
    name: 'prism',
    getOptions: (lang, meta) => ({ lang }),
    initialize: () => import('./adapter').then((m) => m.runtime),
  },
},

Para más sobre el sistema de plugins, consulta Plugins.

Controla cómo los motores de búsqueda indexan tu sitio y cómo se ven los compartidos en redes sociales.

Propiedad	Tipo	Por Defecto	Descripción
`indexing`	`'all' \| 'none' \| 'noindex' \| 'nofollow'`	`'all'`	Controla la directiva `<meta name="robots">` aplicada a cada página.
`thumbnails`	`ThumbnailConfig`	—	Genera imágenes Open Graph para cada página usando una plantilla de fondo.
`structuredData`	`StructuredData`	—	Emite JSON-LD en el head del documento. Es para buscadores y crawlers, no para el índice de búsqueda interno.

Usa los helpers seguros para Node desde boltdocs en boltdocs.config.ts. Para la API más cómoda, consulta la referencia de Structured Data y usa createStructuredData({ website, article, breadcrumbs }). seo.structuredData también puede definirse en el frontmatter MDX, y <StructuredData /> está disponible para páginas React externas.

import {
  createWebSiteStructuredData,
  defineConfig,
  defineStructuredData,
} from 'boltdocs'

export default defineConfig({
  siteUrl: 'https://docs.example.com',
  seo: {
    structuredData: defineStructuredData(
      createWebSiteStructuredData({
        name: 'Example Docs',
        url: 'https://docs.example.com',
      }),
    ),
  },
})

Los helpers disponibles incluyen createWebSiteStructuredData, createArticleStructuredData y createBreadcrumbStructuredData.

Propiedad	Tipo	Descripción
`background`	`string`	Ruta (relativa a `public/`) a la imagen de fondo usada para thumbnails OG.

Las capacidades experimentales están desactivadas por defecto.

Propiedad	Tipo	Predeterminado	Descripción
`viewTransitions`	`boolean \| { enabled?: boolean; types?: string[] }`	desactivado	Usa la API nativa de View Transitions cuando existe y vuelve a un comportamiento normal cuando no.
`fileRouting`	`boolean`	desactivado	Mapea archivos literales de `docs/pages-external/` a rutas externas.

Consulta Funciones Experimentales para ejemplos prácticos de View Transitions, TransitionLink y limitaciones de file-routing.

Genera un archivo robots.txt en tiempo de compilación.

Propiedad	Tipo	Descripción
`rules`	`RobotsRule[]`	Array de reglas de rastreo. Cada regla acepta `userAgent`, `allow` y `disallow`.
`sitemaps`	`string[]`	URLs completas de tu(s) sitemap(s) para incluir en `robots.txt`.

boltdocs.config.ts

export default defineConfig({
  robots: {
    rules: [
      { userAgent: '*', allow: '/' },
    ],
    sitemaps: ['https://my-project.com/sitemap.xml'],
  },
})

Propiedad	Tipo	Descripción
`ga4`	`GA4Config`	Configuración de Google Analytics 4.
`gtm`	`GTMConfig`	Configuración de Google Tag Manager.

Propiedad	Tipo	Descripción
`measurementId`	`string`	Tu ID de Medición de GA4 (por ejemplo, `'G-XXXXXXXXXX'`). Boltdocs inyecta el script de rastreo automáticamente.

Propiedad	Tipo	Descripción
`tagId`	`string`	Tu ID de Contenedor de Google Tag Manager (por ejemplo, `'GTM-XXXXXX'`).
`dataLayerName`	`string`	Nombre personalizado para el dataLayer de GTM (por defecto `'dataLayer'`).
`preview`	`string`	Cadena de consulta de identificador de preview/entorno de GTM.

Propiedad	Tipo	Requerido	Descripción
`defaultLocale`	`string`	✓	El código de idioma principal (por ejemplo, `'en'`).
`locales`	`string[] \| Record<string, string>`	✓	Todos los códiges de locale soportados.
`localeConfigs`	`Record<string, LocaleConfig>`	—	Configuraciones de visualización por locale (label, direction, htmlLang).

Consulta la guía de Internacionalización para más detalles.

Propiedad	Tipo	Requerido	Descripción
`defaultVersion`	`string`	✓	La ruta de versión considerada como la actual por defecto.
`versions`	`VersionConfig[]`	✓	Lista ordenada de versiones disponibles.
`prefix`	`string`	—	Cadena antepuesta a la ruta de carpeta de cada versión.

Consulta la guía de Versionado para más detalles.

Configura el sistema de colecciones dinámicas — perfecto para blogs, notas de release, changelogs o cualquier contenido que siga una estructura repetitiva. Las colecciones se definen con nombres de carpeta entre corchetes (por ejemplo, [blog]) dentro de tu directorio docs/.

Propiedad	Tipo	Por Defecto	Descripción
`postsPerPage`	`number`	`10`	Número de publicaciones mostradas por página en los índices de listado de colecciones.
`defaultCollection`	`string`	`'blog'`	El ID de colección usado por `BlogList` cuando no se especifica una colección explícitamente.
`dateFormat`	`string`	`'MMMM dd, yyyy'`	Cadena de formato de fecha para renderizar las fechas de publicación en páginas de listado.
`sortBy`	`'date' \| 'title' \| 'sidebarPosition'`	`'date'`	Campo usado para ordenar publicaciones dentro de una colección.

boltdocs.config.ts

export default defineConfig({
  collections: {
    postsPerPage: 12,
    defaultCollection: 'blog',
    dateFormat: 'MMM dd, yyyy',
    sortBy: 'date',
  },
})

Configuración Rápida

Las colecciones funcionan de fábrica sin ninguna configuración. Simplemente crea una carpeta entre corchetes como [blog] dentro de docs/ y agrega tus archivos MDX. Usa collections solo cuando necesites sobreescribir los valores por defecto.

Consulta la guía de Colecciones para más detalles sobre convenciones de carpetas, vistas personalizadas y datos de loaders.

Un mecanismo poderoso para personalizar cómo aparecen los directorios en el sidebar sin escribir ningún código. Boltdocs escanea automáticamente archivos meta.json dentro de tu directorio docs/ y los fusiona en la configuración del sidebar en tiempo de compilación.

Propiedad	Tipo	Descripción
`title`	`string`	Título de visualización personalizado para el directorio en el sidebar.
`order`	`number \| string[]`	Posición numérica u ordenamiento explícito de elementos hijos dentro del directorio.
`icon`	`string`	Nombre del icono mostrado junto a la etiqueta del directorio (soporta iconos de Lucide).
`collapsible`	`boolean`	Si el grupo del sidebar es plegable.
`collapsed`	`boolean`	Si el grupo inicia en estado colapsado.

Coloca un meta.json (o _meta.json) en cualquier directorio para configurarlo automáticamente:

(guides)/getting-started/meta.json

{
  "title": "Primeros Pasos",
  "order": 1,
  "icon": "Rocket",
  "collapsed": false
}

También puedes definir metadatos directamente en boltdocs.config.ts para directorios que no controlas o cuando prefieres una configuración centralizada:

boltdocs.config.ts

export default defineConfig({
  directoryMeta: {
    'guides/getting-started': {
      title: 'Inicio Rápido',
      icon: 'Zap',
      order: 0,
    },
    'api': {
      title: 'Referencia API',
      icon: 'Code2',
      collapsed: false,
    },
  },
})

Formato de Ruta

Las claves de directorio usan la ruta relativa desde tu directorio docs/ (por ejemplo, 'guides/getting-started'). El directorio raíz se representa como '.'.

Configura headers de respuesta, ajustes de seguridad y Content Security Policy (CSP).

Propiedad	Tipo	Descripción
`enableCSP`	`boolean`	Establece en `true` para inyectar un header de Content Security Policy seguro por defecto.
`headers`	`Record<string, string>`	Headers HTTP personalizados enviados en todas las solicitudes.
`customHeaders`	`Record<string, string>`	Headers de sobreescritura adicionales para el servidor web.

boltdocs.config.ts

import { defineConfig } from 'boltdocs'
import mermaidPlugin from '@bdocs/plugin-mermaid'

export default defineConfig({
  siteUrl: 'https://my-project.com',
  base: '/docs',
  plugins: [mermaidPlugin()],
  seo: {
    indexing: 'all',
    thumbnails: {
      background: '/og-image.webp',
    },
  },
  theme: {
    title: 'My Project',
    description: 'My project documentation.',
    logo: {
      dark: '/logo-light.svg',
      light: '/logo-dark.svg',
      alt: 'My Project Logo',
    },
    githubRepo: 'my-org/my-project',
    codeHighlighting: {
      engine: 'shiki',
      theme: {
        light: 'github-light',
        dark: 'github-dark',
      },
    },
    editLink: 'https://github.com/my-org/my-project/edit/main/docs/:path',
    tabs: [
      { id: 'guides', text: 'Guides', icon: 'BookOpen' },
      { id: 'api', text: 'API', icon: 'Code2' },
    ],
    navbar: [
      { label: 'Docs', href: '/docs' },
    ],
  },
  robots: {
    rules: [{ userAgent: '*', allow: '/' }],
    sitemaps: ['https://my-project.com/sitemap.xml'],
  },
  collections: {
    postsPerPage: 12,
    defaultCollection: 'blog',
    sortBy: 'date',
  },
  directoryMeta: {
    'guides/getting-started': {
      title: 'Inicio Rápido',
      icon: 'Zap',
      order: 0,
    },
  },
  integrations: {
    ga4: {
      measurementId: 'G-XXXXXXXXXX',
    },
  },
})

Jesús Alcalá

Last updated on October 18, 2026

Configuración

`aliases`

`ThemeConfig`

`LogoConfig`

`CodeThemeConfig`

`CodeHighlightConfig`

Motores personalizados vía plugins

`SeoConfig`

Datos estructurados

`ThumbnailConfig`

`ExperimentalConfig`

`RobotsConfig`

`IntegrationsConfig`

`GA4Config`

`GTMConfig`

`I18nConfig`

`VersionsConfig`

`CollectionsConfig`

`directoryMeta`

Usando Archivos `meta.json` (Recomendado)

Usando `directoryMeta` en Configuración

`SecurityConfig`

Ejemplo Completo

Was this page helpful?