Comandos CLI

La CLI de Boltdocs impulsa todo el flujo de trabajo: arranca tu servidor de desarrollo, construye el sitio estático, previsualiza el bundle de producción, audita tus plugins en busca de advertencias de seguridad, comprueba la salud de tu documentación y genera páginas de changelog.

La ejecutas con npx boltdocs o — una vez añadida a los scripts de tu package.json — con pnpm docs:dev, pnpm docs:build y compañía:

{
  "scripts": {
    "docs:dev": "boltdocs dev",
    "docs:build": "boltdocs build",
    "docs:preview": "boltdocs preview",
    "docs:audit": "boltdocs audit",
    "docs:doctor": "boltdocs doctor"
  }
}

Todos los comandos aceptan un argumento posicional opcional [root] que apunta a un directorio de proyecto. Por defecto es process.cwd().

dev — servidor de desarrollo

Inicia un servidor de desarrollo Vite de alto rendimiento con Hot Module Replacement (HMR) instantáneo para archivos MDX, ediciones de estilos y recargas en caliente de configuración.

• Uso: boltdocs dev [root] [options] — o simplemente boltdocs [root] [options]

Opciones del servidor dev

build — build de producción

Compila tu documentación en activos HTML y JavaScript completamente estáticos y altamente optimizados mediante el motor de Static Site Generation (SSG) de React.

• Uso: boltdocs build [root]

La salida se genera en dist/ (configurable con outDir en boltdocs.config.ts).

preview — prueba el bundle de producción

Sirve el bundle estático generado desde dist/ para que verifiques rendimiento, redirecciones, etiquetas SEO y el renderizado de páginas antes de desplegar.

• Uso: boltdocs preview [root] [options]

Opciones de preview

audit — escaneo de seguridad de plugins

Realiza un análisis estático y rápido del código fuente de cada plugin configurado en tu proyecto. Escanea comportamientos potencialmente sensibles — llamadas a procesos hijos y código dinámico, acceso a red, lecturas y escrituras de archivos, lectura de variables de entorno y señales de metadatos como scripts de instalación o licencias faltantes — antes de que compiles o publiques.

El escaneo nunca ejecuta código de plugins: solo lee package.json y los archivos fuente de node_modules. (Cargar tu configuración sí evalúa el propio archivo de config, pero nunca se ejecuta ningún hook de plugin, plugin de Vite ni script de instalación.)

• Uso: boltdocs audit [root]

Exit codes (contrato para CI)

El comando es fail-closed: un plugin no resuelto o no escaneado se trata como no confiable y nunca cuenta como "pasado". Úsalo como puerta antes de fusionar plugins de terceros:

- run: pnpm docs:build
- run: pnpm docs:audit

Si el audit devuelve 1, tu job de CI falla — exactamente cuando quieres que un humano revise un plugin antes de que se publique.

doctor — diagnósticos y verificación de integridad

Ejecuta comprobaciones automatizadas en tu directorio de documentación para encontrar enlaces rotos, frontmatter malformado, traducciones faltantes y otros problemas estructurales.

# Ejecutar doctor en la carpeta actual
npx boltdocs doctor

# Corregir automáticamente problemas reparables
npx boltdocs doctor --fix

# Verificar URLs externas además de las rutas internas
npx boltdocs doctor --check-external

# Inicializar un archivo doctor.json por defecto
npx boltdocs doctor --init

# Verificar el rendimiento del build contra presupuestos configurados
npx boltdocs doctor --budget

Opciones de doctor

Configurar doctor.json

Crea un doctor.json en la raíz de tu proyecto para personalizar comprobaciones, severidades y comportamiento en CI. Ejecuta boltdocs doctor --init para generarlo y luego ajústalo:

{
  "$schema": "https://boltdocs.vercel.app/schemas/doctor-config.schema.json",
  "checks": {
    "metadata": {
      "enabled": true,
      "titleMin": 10,
      "titleMax": 60,
      "descriptionMin": 50,
      "required": ["title", "description"]
    },
    "links": {
      "internal": true,
      "external": false,
      "timeout": 10000,
      "concurrency": 10
    },
    "i18n": { "enabled": true },
    "performance": {
      "enabled": true,
      "budgets": {
        "maxJSBundleSize": "200kb",
        "maxCSSBundleSize": "30kb",
        "maxPageHTMLSize": "80kb",
        "maxImagesKB": 500,
        "maxBuildTime": 30000,
        "maxFontCount": 3
      }
    }
  },
  "fix": {
    "confirmChanges": false,
    "backupFiles": false,
    "backupPath": ".boltdocs/backups"
  },
  "reporting": {
    "format": "pretty",
    "outputFile": ".boltdocs/reports/doctor.json",
    "failOnError": false,
    "maxWarnings": -1
  },
  "severity": {
    "missingTranslation": "warning",
    "brokenLink": "high",
    "brokenAnchor": "warning",
    "malformedFrontmatter": "high",
    "invalidFrontmatter": "high",
    "budgetExceeded": "warning"
  }
}

checks

Opciones de metadata: titleMin (10), titleMax (60), descriptionMin (50), required (["title", "description"]), optional ([]), validateDates (false).

Opciones de enlaces: internal (true), external (false), timeout (10000 ms), concurrency (10), ignore ([] — patrones regex o URLs exactas a omitir).

Los presupuestos de rendimiento aceptan maxJSBundleSize, maxCSSBundleSize, maxPageHTMLSize (strings como "200kb"), además de maxImagesKB, maxBuildTime (ms) y maxFontCount.

fix

reporting

generate-changelog — generador de changelog

Analiza un CHANGELOG.md unificado (formatos Keep a Changelog, Standard Version o Semantic Release) y lo descompone en páginas MDX individuales por versión formateadas para el tema de Boltdocs.

# Descomponer CHANGELOG.md en páginas bajo docs/changelog
npx boltdocs generate-changelog CHANGELOG.md

Opciones de changelog

Salida

Cada versión se agrupa por tipo de actualización (Features, Bug Fixes, Performance, Refactor, Documentation, Chore) y se escribe como página incremental:

docs/changelog/
├── 1.v2.0.0.md
├── 2.v1.1.0.md
└── 3.v1.0.0.md

Para mostrar las páginas generadas en el navbar, enlázalas desde boltdocs.config.ts:

export default defineConfig({
  theme: {
    navbar: [
      { label: 'Documentation', href: '/docs' },
      { label: 'Changelog', href: '/changelog' },
    ],
  },
})

Jesús Alcalá

Last updated on October 18, 2026