Boltdocs Logo
GuíasIntegracionesAPIPluginsComponentesLanzamientos

Mermaid

El plugin `@bdocs/plugin-mermaid` integra Mermaid.js en Boltdocs. Transforma automáticamente los bloques de código `mermaid` estándar en diagramas interactivos y responsivos que se sincronizan dinámicamente con tus preferencias de tema claro y oscuro.

Instalación y Inicio RápidoLink

Comienza añadiendo el paquete del plugin a tu proyecto de documentación.

1. Instalar el paqueteLink

sh
pnpm add @bdocs/plugin-mermaid

2. Registrar el pluginLink

Añade el plugin al arreglo plugins en tu archivo de configuración:

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

export default defineConfig({
  plugins: [mermaidPlugin()],
})

Referencia de la APILink

MermaidPluginOptionsLink

Configuración que se pasa al inicializador mermaidPlugin().

PropiedadTipoPredeterminadoDescripción
themesMermaidThemesundefinedVariables de tema personalizadas para coincidir con tu marca corporativa.

MermaidThemesLink

Configuraciones personalizadas para los modos de visualización claro y oscuro.

PropiedadTipoPredeterminadoDescripción
lightMermaidThemeVariablesdefaultLightThemeOverrides de tema aplicados cuando el modo claro del sitio está activo.
darkMermaidThemeVariablesdefaultDarkThemeOverrides de tema aplicados cuando el modo oscuro del sitio está activo.

MermaidThemeVariablesLink

Lista completa de variables de color disponibles para personalizar el estilo de los nodos del diagrama.

PropiedadTipoPredeterminadoDescripción
primaryColorstringClaro: '#f8fafc'
Oscuro: '#1e293b'		Color de fondo para nodos primarios.
primaryTextColorstringClaro: '#0f172a'
Oscuro: '#f8fafc'		Color de texto para nodos primarios.
primaryBorderColorstringClaro: '#e2e8f0'
Oscuro: '#334155'		Color de borde para nodos primarios.
lineColorstringClaro: '#64748b'
Oscuro: '#94a3b8'		Color para líneas de conexión y flechas.
secondaryColorstringClaro: '#f1f5f9'
Oscuro: '#0f172a'		Color de fondo para elementos secundarios.
tertiaryColorstringClaro: '#ffffff'
Oscuro: '#1e293b'		Color de fondo para elementos terciarios.
nodeBorderstringClaro: '#e2e8f0'
Oscuro: '#334155'		Color de borde predeterminado para nodos.
mainBkgstringClaro: '#ffffff'
Oscuro: '#0f172a'		Color de fondo del canvas principal.
nodeTextColorstringClaro: '#0f172a'
Oscuro: '#f8fafc'		Color de texto predeterminado dentro de los nodos.
edgeLabelBackgroundstringClaro: '#f8fafc'
Oscuro: '#1e293b'		Color de fondo para etiquetas de conectores.
clusterBkgstringClaro: '#f8fafc'
Oscuro: '#1e293b'		Color de fondo para grupos de clúster.
clusterBorderstringClaro: '#e2e8f0'
Oscuro: '#334155'		Color de borde para grupos de clúster.

Props del Componente MermaidLink

Propiedades soportadas al usar el componente React <Mermaid /> directamente en MDX.

PropiedadTipoPredeterminadoDescripción
chartstring(Requerido)La definición de marcado del diagrama Mermaid.
configMermaidConfigundefinedOverrides de tema en línea específicos para esta instancia de diagrama.

Ejemplos DetalladosLink

Temas PersonalizadosLink

Puedes personalizar los temas pasando overrides de variables directamente:

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

export default defineConfig({
  plugins: [
    mermaidPlugin({
      themes: {
        light: {
          primaryColor: '#e0f2fe',
          primaryTextColor: '#0369a1',
          primaryBorderColor: '#bae6fd',
          lineColor: '#0284c7',
        },
        dark: {
          primaryColor: '#0c4a6e',
          primaryTextColor: '#e0f2fe',
          primaryBorderColor: '#0284c7',
          lineColor: '#38bdf8',
        },
      },
    }),
  ],
})

Sintaxis de ComponentesLink

Para layouts avanzados, puedes invocar el componente JSX directamente:

mdx
<Mermaid chart={`
  flowchart LR
    A[Start] --> B[Process]
    B --> C[End]
`} />
Recomendación de Sintaxis

Aunque tanto los bloques markdown como las variantes de etiquetas JSX producen resultados equivalentes, recomendamos los bloques de código markdown estándar (```mermaid) para una máxima legibilidad en los editores de código.

Solución de ProblemasLink

Los diagramas no se renderizanLink

  • Verifica la Configuración: Asegúrate de que mermaidPlugin() esté registrado en el arreglo de plugins de tu boltdocs.config.ts.
  • Verifica el Identificador de Lenguaje: La apertura de tu bloque de código markdown debe ser exactamente ```mermaid.
  • Revisa la Sintaxis: Revisa la consola de tu navegador web para errores de sintaxis generados por el compilador de Mermaid (por ejemplo, paréntesis sin cerrar o errores tipográficos en las conexiones de nodos).

Los temas no se sincronizanLink

El plugin se conecta al proveedor de modo oscuro del sitio. Si los temas no coinciden:

  • Asegúrate de que tus layouts personalizados consuman el hook useTheme() exportado por boltdocs/client para mantenerse sincronizado con la configuración global de la aplicación.

Los diagramas grandes se cortanLink

Por defecto, Boltdocs envuelve los diagramas en un contenedor responsivo con desplazamiento. Si necesitas que los diagramas se escalen para ajustarse al contenedor padre, añade lo siguiente a tu hoja de estilos CSS global personalizada:

css
.mermaid-container svg {
  max-width: 100%;
  height: auto;
}
Jesús Alcalá
Last updated on October 18, 2026

Was this page helpful?