Capítulo 6: Personalización Avanzada e Integración en Sitios Estáticos

En las entregas anteriores aprendiste a construir desde diagramas de flujo y secuencias hasta arquitecturas ER y cronogramas de Gantt. En este capítulo final exploraremos cómo tomar el control estético absoluto de tus diagramas mediante la directiva de inicialización %%{init}%% y cómo integrar Mermaid de forma nativa en generadores de sitios estáticos (SSG) como Astro, Hugo y Jekyll.

1. Configuración Global con la Directiva %%{init}%%

La directiva %%{init}%% permite inyectar configuraciones en formato JSON directamente en el archivo .mmd. Se coloca en la primera línea del archivo y sobrescribe los parámetros por defecto de Mermaid.

Sintaxis básica

%%{init: { 'theme': 'forest', 'themeVariables': { 'darkMode': true }}}%%
flowchart LR
    A[Inicio] --> B[Procesamiento]

  

%%{init: { 'theme': 'forest', 'themeVariables': { 'darkMode': true }}}%%
flowchart LR
    A[Inicio] --> B[Procesamiento]

Temas globales integrados

Mermaid incluye cuatro temas base listos para usar:

• default: Eslogan visual clásico con tonos azules e grises.
• neutral: Diseño sobrio en escala de grises y bordes finos (ideal para documentación impresa o académica).
• dark: Fondo oscuro con contraste alto para modo noche.
• forest: Esquema de color basado en tonos verdes y orgánicos.

2. Personalización Profunda con themeVariables

Para adaptar un diagrama exactamente a la paleta de colores de tu blog o marca personal, utiliza la propiedad themeVariables.

Variables clave reutilizables

• primaryColor / primaryTextColor: Color de fondo y texto principal de los nodos.
• primaryBorderColor: Color del borde de los nodos principales.
• lineColor: Color de las flechas y conexiones.
• fontFamily: Tipografía principal de todo el diagrama.
• fontSize: Tamaño de fuente base.

Ejemplo: Diagrama con identidad corporativa personalizada

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'fontFamily': 'Fira Code, monospace',
      'fontSize': '14px',
      'primaryColor': '#2b2d42',
      'primaryTextColor': '#edf2f4',
      'primaryBorderColor': '#8d99ae',
      'lineColor': '#ef233c',
      'tertiaryColor': '#d90429'
    }
  }
}%%
flowchart TD
    Cliente[Cliente Web / App] -->|HTTPS| Gateway[API Gateway]
    Gateway --> Microservicio[Servicio de Datos]
    Microservicio --> Cache[(Redis Cache)]

  

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'fontFamily': 'Fira Code, monospace',
      'fontSize': '14px',
      'primaryColor': '#2b2d42',
      'primaryTextColor': '#edf2f4',
      'primaryBorderColor': '#8d99ae',
      'lineColor': '#ef233c',
      'tertiaryColor': '#d90429'
    }
  }
}%%
flowchart TD
    Cliente[Cliente Web / App] -->|HTTPS| Gateway[API Gateway]
    Gateway --> Microservicio[Servicio de Datos]
    Microservicio --> Cache[(Redis Cache)]

3. Integración en Generadores de Sitios Estáticos (SSG)

Publicar tus diagramas en tu blog personal o sitio técnico es sencillo y no requiere compilación previa a imagen si aprovechas el renderizado del lado del cliente o del compilador del SSG.

Integración en Astro

En Astro, la forma más limpia y ligera es utilizar la librería cliente o una integración como astro-mermaid.

Opción lado del cliente (sin extensiones):

Añade un script en tu plantilla base o componente Markdown (.astro):

<!-- Componente Astro / Layout -->
<script>
  import mermaid from 'mermaid';
  mermaid.initialize({ startOnLoad: true, theme: 'dark' });
</script>

Simplemente escribe tus bloques de código Markdown con el lenguaje mermaid:

```mermaid
flowchart LR
    A --> B
```

Integración en Hugo

En Hugo, puedes utilizar un Shortcode personalizado para renderizar los bloques de código automáticamente.

1. Crea el archivo layouts/shortcodes/mermaid.html:

<div class="mermaid">
  {{ .Inner }}
</div>
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>

1. Úsalo dentro de tus archivos Markdown .md:

{{< mermaid >}}
flowchart TD
    A[Entrada] --> B[Salida]
{{< /mermaid >}}

Integración en Jekyll

En Jekyll (utilizado habitualmente con GitHub Pages), puedes integrar el cliente JS en el archivo _layouts/post.html antes de cerrar la etiqueta </body>:

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    mermaid.initialize({
      startOnLoad: true,
      theme: 'default'
    });
  });
</script>

Cualquier bloque con la etiqueta ```mermaid se convertirá automáticamente en un gráfico vectorial SVG cuando tus lectores carguen la página.

Integración en Ghost

En el blog Ghost, para que se renderice correctamente el código mermaid es necesario que en el artículo en el que quieras usarlo debes de inyectar el interprete.
Para ello en el apartado de Code Injection Post header {{ghost_head}} debes de incluir el siguiente código:

<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    mermaid.initialize({ startOnLoad: true, theme: 'default' });
  });
</script>

Y en el artículo para que se interprete correctamente el código mermaid debes de insertarlo como bloque HTML envolviendo el codigo "mermaid" entre las siguientes etiquetas:

<pre class="mermaid">
  
</pre>

Ejemplo de bloque HTML para incluir código mermaid:

<pre class="mermaid">

flowchart LR
A --> B --> C --> D

</pre>

4. Estrategia de Publicación Automatizada desde Debian

Si prefieres publicar imágenes SVG estáticas en lugar de cargar JavaScript en el navegador de tus lectores (optimizando la velocidad de carga / SEO de tu blog), puedes integrar mmdc en tu flujo de publicación desde Debian mediante un script de compilación rápida.

#!/bin/bash
# Script de compilación masiva para blog: mmd2svg.sh

# Crear directorio de salida si no existe
mkdir -p static/imagenes/diagramas

# Buscar todos los archivos .mmd en la carpeta content/ y convertirlos a SVG
for file in content/diagramas/*.mmd; do
    filename=$(basename "$file" .mmd)
    echo "Compilando $file a SVG..."
    mmdc -i "$file" -o "static/imagenes/diagramas/${filename}.svg" -t dark -b transparent
done

echo "¡Compilación finalizada con éxito!"

Asigna permisos de ejecución y ejecútalo en tu entorno Debian antes de desplegar tu sitio:

chmod +x mmd2svg.sh
./mmdc2svg.sh

5. Generación de ficheros PDF con Pandoc

Pandoc por sí solo no interpreta ni renderiza bloques de código Mermaid al generar un PDF. Pandoc trata el contenido dentro de ```mermaid simplemente como texto plano con formato de bloque de código (igual que si fuera Python o Bash).

Para que Pandoc transforme ese código en gráficos vectoriales o imágenes dentro del PDF final, necesitas utilizar un filtro.

Solución Recomendada: mermaid-filter

La opción más sencilla y robusta en Linux/Debian es usar el filtro global mermaid-filter, el cual utiliza internamente tu instalación de mmdc para procesar los diagramas durante la conversión.

1. Instalación en Debian

Instala el filtro de forma global con npm:

sudo npm install -g mermaid-filter

(Asegúrate de que también tienes instalado puppeteer o las dependencias de Chromium que usas con mmdc).

2. Compilación del PDF con Pandoc

Al ejecutar el comando de Pandoc, añade el parámetro --filter mermaid-filter:

pandoc mi_manual.md -o mi_manual.pdf --filter mermaid-filter

Cuando Pandoc encuentra un bloque ```mermaid, se lo pasa a mermaid-filter, este invoca a mmdc en segundo plano, genera una imagen SVG/PNG temporal e inserta la imagen de forma transparente en el PDF final.

Si sigues teniendo problemas con el uso de mermaid-filter simplemente ejecuta lo siguiente:

sudo apt update
sudo apt -y installchromium chromium-sandbox

Y antes de usar pandoc exporta lo siguiente:

export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
export PUPPETEER_ARGS="--no-sandbox"

Si quieres dejar esta exportación asignada permanentemente cada vez que hagas login con tu usuario, simplemente ejecuta:

echo 'export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium' >> ~/.bashrc
echo 'export PUPPETEER_ARGS="--no-sandbox"' >> ~/.bashrc

Para cargar estas variables en tu sesión actual , sin tener que cerrar y abrir sesión de nuevo, ejecuta:

# Cargamos exports para la sesión actual
source ~/.bashrc

Alternativa nativa sin filtros: pandoc-plot o Script previo

Si prefieres no instalar filtros globales de Node.js, la estrategia habitual en Debian es:

1. Extraer y compilar los gráficos a SVG primero usando un script Bash con mmdc.
2. En el archivo Markdown, referenciar las imágenes generadas (![Diagrama](diagrama1.svg)).
3. Compilar con Pandoc pasando el motor pdfengine adecuado (como xelatex o weasyprint que soportan SVG nativamente):

pandoc mi_manual.md -o mi_manual.pdf --pdf-engine=xelatex

Consejo para tu PDF: Para asegurar que los diagramas no se corten entre páginas en el PDF resultante, es recomendable usar WeasyPrint o wkhtmltopdf como motor PDF de Pandoc (--pdf-engine=weasyprint), ya que manejan el renderizado de gráficos vectoriales SVG e imágenes integradas de forma excelente.