Capítulo 1: Introducción a Mermaid, Sintaxis Básica y Compilación en Debian

Bienvenido al primer capítulo del manual definitivo de Mermaid.

En esta guía aprenderás a transformar ideas y flujos de trabajo en diagramas claros mediante código plano, eliminando la necesidad de arrastrar formas manualmente en herramientas de diseño tradicionales.

1. ¿Qué es Mermaid y el paradigma Diagrams as Code?

Mermaid es una herramienta basada en JavaScript que utiliza una sintaxis inspirada en Markdown para generar y renderizar diagramas complejos de forma dinámica.

Forma parte del paradigma Diagrams as Code (Diagramas como Código), el cual ofrece ventajas clave frente a las herramientas visuales tradicionales:

• Control de versiones: Los diagramas se almacenan como texto plano, permitiendo rastrear cambios mediante Git, realizar diffs y trabajar en equipo fácilmente.
• Mantenibilidad: Modificar un diagrama requiere cambiar un par de líneas de texto; no hace falta reordenar manualmente todo el lienzo ni reajustar conectores.
• Integración nativa: Es compatible de forma predeterminada con plataformas como GitHub, GitLab, Notion, Obsidian y diversos generadores de sitios estáticos (Hugo, Jekyll, Astro).

2. Sintaxis Básica: La Estructura de un Diagrama

Todo diagrama en Mermaid se define declarando primero el tipo de diagrama y su orientación, seguido de la definición de los nodos y sus conexiones.

Tipos de orientación

Para diagramas de flujo (flowchart), las orientaciones principales son:

• TD / TB (Top-Down / Top-Bottom): De arriba hacia abajo.
• LR (Left-Right): De izquierda a derecha.
• RL (Right-Left): De derecha a izquierda.
• BT (Bottom-Top): De abajo hacia arriba.

Formas de los nodos

Las formas se definen encapsulando el texto del nodo dentro de diferentes tipos de corchetes o paréntesis:

flowchart LR
    A[Rectángulo estándar]
    B(Esquinas redondeadas)
    C([Forma de píldora])
    D[[Subrutina]]
    E[(Base de datos)]
    F((Círculo))
    G>Asimetría / Banderín]
    H{Rombo / Decisión}

flowchart LR
    A[Rectángulo estándar]
    B(Esquinas redondeadas)
    C([Forma de píldora])
    D[[Subrutina]]
    E[(Base de datos)]
    F((Círculo))
    G>Asimetría / Banderín]
    H{Rombo / Decisión}

Tipos de conexiones (enlaces)

Las líneas entre nodos se definen según el estilo de conector:

• Flecha estándar: A --> B
• Línea abierta (sin flecha): A --- B
• Texto en la flecha: A -- "Texto del enlace" --> B o A -->|Texto del enlace| B
• Línea punteada: A -.- B o A -. "Texto" .-> B
• Línea gruesa: A ==> B o A == "Texto" ==> B

Ejemplo completo: Diagrama de flujo inicial

Guarda el siguiente bloque en un archivo llamado ejemplo1.mmd:

flowchart TD
    Inicio([Inicio del Proceso]) --> Consulta[(Consultar Base de Datos)]
    Consulta --> Decision{¿Existe el usuario?}
    
    Decision -- Sí --> Login[Iniciar Sesión]
    Decision -- No --> Registro[Crear Cuenta Nueva]
    
    Login --> Fin([Fin])
    Registro --> Fin

flowchart TD
    Inicio([Inicio del Proceso]) --> Consulta[(Consultar Base de Datos)]
    Consulta --> Decision{¿Existe el usuario?}
    
    Decision -- Sí --> Login[Iniciar Sesión]
    Decision -- No --> Registro[Crear Cuenta Nueva]
    
    Login --> Fin([Fin])
    Registro --> Fin  

3. Compilación e Instalación de mmdc en Debian

Para convertir tus archivos de definición .mmd a formatos gráficos como PNG, SVG o PDF desde la terminal de Debian, utilizaremos Mermaid CLI (mmdc).

Paso 1: Requisitos previos (Node.js y npm)

Asegúrate de tener instalados Node.js y npm en tu sistema Debian. Si no los tienes, puedes instalarlos con:

sudo apt update
sudo apt install -y nodejs npm

Paso 2: Instalación de @mermaid-js/mermaid-cli

Puedes instalar la herramienta de forma global ejecutando:

sudo npm install -g @mermaid-js/mermaid-cli

Para verificar que la instalación fue exitosa:

mmdc --version

Nota sobre Puppeteer en Debian: mmdc utiliza Chromium sin interfaz (headless) a través de Puppeteer para renderizar los diagramas. Si al ejecutar el comando obtienes un error por falta de dependencias de Chromium, instala las bibliotecas necesarias con:

Si sigue sin funcionar correctamente incluso tras la instalación de las librerías, prueba a instalar chrome-headless-shell de la siguiente forma:

npx puppeteer browsers install chrome-headless-shell

Paso 3: Compilar el diagrama a formatos gráficos

Una vez instalado mmdc, puedes compilar tu archivo ejemplo1.mmd fácilmente:

Generar imagen PNG:

mmdc -i ejemplo1.mmd -o ejemplo1.png

Generar gráfico vectorial SVG (Recomendado para páginas web y blogs):

mmdc -i ejemplo1.mmd -o ejemplo1.svg

Generar documento PDF:

mmdc -i ejemplo1.mmd -o ejemplo1.pdf

Aplicar temas de color nativos

Puedes especificar el tema directamente en el comando con el parámetro -t:

# Opción de tema: default, forest, dark, neutral
mmdc -i ejemplo1.mmd -o ejemplo1_dark.png -t dark

Resumen del Capítulo

1. Estructura básica: Define la orientación (flowchart TD), los nodos con sus respectivas formas [ ], ( ), { } y conéctalos mediante flechas -->.
2. Compilación en Debian: Con mmdc -i archivo.mmd -o imagen.png conviertes rápidamente tus diagramas en imágenes listas para publicar en tu blog.