Diagramas Mermaid

Mermaid es una librería de JavaScript que convierte texto con sintaxis sencilla en diagramas vectoriales: flujos, secuencias, Gantt, clases y más. En lugar de arrastrar cajas en una herramienta gráfica, describes el diagrama como código, lo que lo hace ideal para documentación técnica que vive junto al código fuente y se versiona con Git.

Diagrama de flujo (Flowchart)

El tipo más usado. Define nodos y conexiones con texto:

flowchart LR
    A[Inicio] --> B{¿Es válido?}
    B -- Sí --> C[Procesar]
    B -- No --> D[Mostrar error]
    C --> E[Fin]
    D --> E

• LR significa left to right (izquierda a derecha). Otras opciones: TD (top-down), BT, RL.
• [ ] dibuja un rectángulo, { } un rombo (decisión), ( ) un rectángulo redondeado.
• --> es una flecha normal; -- texto --> añade una etiqueta a la conexión.

Diagrama de secuencia

Ideal para documentar la comunicación entre sistemas o actores:

sequenceDiagram
    participant U as Usuario
    participant API
    participant BD as Base de datos
    U->>API: POST /login
    API->>BD: SELECT usuario WHERE email=...
    BD-->>API: {id: 1, hash: ...}
    API-->>U: 200 OK + JWT

Las flechas -->> representan respuestas (línea discontinua); ->> son peticiones (línea continua).

Diagrama de Gantt

Útil para planificar proyectos con fechas:

gantt
    title Plan de lanzamiento
    dateFormat  YYYY-MM-DD
    section Backend
    Diseño de la API      :done,    des1, 2026-07-01, 7d
    Desarrollo            :active,  dev1, after des1, 14d
    section Frontend
    Maquetación           :         maq1, 2026-07-08, 10d
    Integración           :         int1, after maq1, 7d

Diagrama de clases (UML)

classDiagram
    class Usuario {
        +String nombre
        +String email
        +login()
    }
    class Pedido {
        +int id
        +Date fecha
    }
    Usuario "1" --> "*" Pedido : realiza

Cómo insertar Mermaid en distintos entornos

En GitHub / GitLab / Notion / Obsidian: encierra el código entre triple backtick con mermaid como lenguaje. Se renderiza automáticamente en archivos .md, issues y pull requests.

En HTML (sin build step):

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<pre class="mermaid">
flowchart LR
    A --> B
</pre>
<script>mermaid.initialize({ startOnLoad: true });</script>

Con la CLI (exportar a PNG o SVG estático):

npm install -g @mermaid-js/mermaid-cli
mmdc -i diagrama.mmd -o diagrama.svg

Ventajas frente a herramientas gráficas

• Versionado: el diagrama es texto, vive en el repositorio y los cambios aparecen en el diff de Git.
• Consistencia: el estilo es uniforme sin depender de quién lo edite ni de su versión de la herramienta.
• Velocidad: describir un flujo sencillo en Mermaid suele ser más rápido que dibujarlo con el ratón.
• Sin licencias ni exportaciones: es open source; el diagrama siempre está donde está el código, no en una herramienta externa.

Errores comunes

• Tipo de diagrama con mayúscula: flowChart (con C mayúscula) falla; el tipo debe ser exactamente flowchart, sequenceDiagram, gantt, etc.
• Flechas incorrectas: -> no es válido en flowchart; usa -->. En sequenceDiagram usa ->> o -->>.
• Caracteres especiales sin escapar: texto de nodos con <, > o " puede romper el diagrama; sustitúyelos por sus entidades HTML equivalentes o encierra el texto entre comillas dobles dentro del nodo.
• Nombres de nodos con espacios: A[Mi Nodo] funciona en la mayoría de casos, pero si el texto tiene paréntesis u otros caracteres especiales, usa comillas: A["Nodo (especial)"].