@bdocs/plugin-mermaid

Instalación y Inicio Rápido

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

1. Instalar el paquete

pnpm add @bdocs/plugin-mermaid

2. Registrar el plugin

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

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

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

Conceptos y Arquitectura

El plugin Mermaid utiliza un pipeline de compilación híbrido para mantener tu documentación rápida:

graph LR
    A[Markdown Source] -->|Remark Transform| B[MDX Component Prep]
    B -->|SSG compilation| C[Light HTML Skeleton]
    C -->|Lazy Client Import| D[Interactive SVG Render]

1. Transformación en Tiempo de Compilación: Cuando Boltdocs parsea tus archivos markdown, el compilador Remark del plugin encuentra bloques de código marcados como mermaid. Los compila en componentes React estándar <Mermaid /> e inyecta el texto crudo del diagrama como una prop.

2. Renderizado Dinámico del Lado del Cliente: Para evitar tamaños de bundle JavaScript enormes en tus páginas estáticas, el motor de Mermaid.js se carga dinámicamente solo cuando un diagrama entra en el viewport del usuario. Si una página no contiene diagramas, no se envía código de Mermaid al cliente.

Referencia de la API

MermaidPluginOptions

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

MermaidThemes

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

MermaidThemeVariables

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

Props del Componente Mermaid

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

Ejemplos Detallados

Temas Personalizados

Puedes personalizar los temas pasando overrides de variables directamente:

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 Componentes

Para layouts avanzados, puedes invocar el componente JSX directamente:

<Mermaid chart={`
  flowchart LR
    A[Start] --> B[Process]
    B --> C[End]
`} />

Solución de Problemas

Los diagramas no se renderizan

• 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 sincronizan

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 cortan

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:

.mermaid-container svg {
  max-width: 100%;
  height: auto;
}