Diagramas Mermaid en Markdown: diagramas de flujo, de secuencia y más

Los diagramas explican procesos, arquitecturas y cronogramas mejor que párrafos de texto. Pero dibujarlos en un editor gráfico implica exportar imágenes, guardarlas junto a la documentación y volver a dibujarlo todo cuando algo cambia.

Mermaid lo resuelve: describes el diagrama en unas pocas líneas de texto dentro de tu archivo Markdown y el visor lo dibuja. El diagrama vive en el mismo archivo, aparece en los diffs y se actualiza tan fácilmente como una frase. GitHub, GitLab, Obsidian, muchos generadores de documentación y Markdown Preview Editor renderizan Mermaid sin configuración adicional.

Cómo añadir un diagrama Mermaid

Crea un bloque de código delimitado y define su lenguaje como mermaid:

markdown```mermaid
flowchart LR
  A[Escribir] --> B[Revisar]
  B --> C{¿Listo?}
  C -- sí --> D[Exportar]
  C -- no --> A
```

El visor lo convierte en esto:

La primera línea indica el tipo de diagrama. Todo lo que viene después describe los nodos y las conexiones.

Diagramas de flujo

Los diagramas de flujo son el tipo más usado. La dirección va después de la palabra clave: TD o TB (de arriba abajo), BT, LR (de izquierda a derecha) o RL.

mermaidflowchart TD
  start([Inicio]) --> input[/Leer el archivo/]
  input --> valid{¿Es válido?}
  valid -- Sí --> save[(Guardar en la base de datos)]
  valid -- No --> error[Mostrar un error]
  error --> input

Los corchetes que rodean una etiqueta definen la forma del nodo:

Conexiones: --> es una flecha, --- una línea sin flecha, -.-> una flecha punteada y ==> una flecha gruesa. Añade una etiqueta con -- texto --> o -->|texto|.

Agrupa nodos relacionados con subgraph:

mermaidflowchart LR
  subgraph Navegador
    editor[Editor] --> preview[Vista previa]
  end
  preview --> export[HTML / PDF]

Diagramas de secuencia

Los diagramas de secuencia muestran cómo los participantes intercambian mensajes a lo largo del tiempo: ideales para API, flujos de autenticación y recorridos de usuario.

mermaidsequenceDiagram
  participant U as Usuario
  participant A as App
  participant S as Servidor
  U->>A: Clic en "Iniciar sesión"
  A->>S: POST /login
  S-->>A: 200 OK + token
  A-->>U: Mostrar el panel
  Note over A,S: El token caduca en 1 hora

->> es una flecha continua (una petición) y -->> una flecha discontinua (una respuesta). Note over, Note left of y Note right of añaden comentarios. Usa bloques loop, alt/else y opt para mostrar repeticiones y ramificaciones.

Diagramas de Gantt

Un diagrama de Gantt convierte una lista de tareas en un cronograma. Las tareas pueden empezar en una fecha o after (después de) otra tarea.

mermaidgantt
  title Sprint de documentación
  dateFormat YYYY-MM-DD
  section Redacción
  Esquema            :done,   a1, 2026-10-01, 2d
  Primer borrador    :active, a2, after a1, 4d
  section Revisión
  Revisión por pares :        a3, after a2, 3d
  Publicación        :milestone, after a3, 0d

Diagramas de estados

Los diagramas de estados describen cómo algo pasa de un estado a otro: un pedido, un documento, un componente de la interfaz.

mermaidstateDiagram-v2
  [*] --> Borrador
  Borrador --> Revisión : enviar
  Revisión --> Borrador : cambios solicitados
  Revisión --> Publicado : aprobar
  Publicado --> [*]

Gráficos circulares

Para una imagen rápida de cómo se reparte un total, un gráfico circular usa una línea por porción:

mermaidpie title En qué se va el tiempo de documentación
  "Redactar" : 45
  "Dar formato" : 15
  "Mantener los diagramas al día" : 40

Mermaid también admite diagramas de clases, diagramas entidad-relación, mapas mentales, líneas de tiempo, gráficos de Git, gráficos de cuadrantes y más. La sintaxis de cada uno está documentada en la web oficial de Mermaid.

Consejos para diagramas legibles

• Hazlos pequeños. Un diagrama con más de 15–20 nodos se vuelve difícil de leer. Divídelo en varios diagramas, uno por idea.
• Elige la dirección a propósito. LR va bien para procesos con pocos pasos; TD, para jerarquías y flujos largos, sobre todo en pantallas estrechas.
• Usa ID cortos y etiquetas legibles. Escribe auth[Comprobar la sesión] en lugar de usar la etiqueta como ID: así las conexiones quedan cortas.
• Pon entre comillas las etiquetas con caracteres especiales: A["Precio: $5 (IVA incl.)"].
• Añade comentarios con %% al principio de una línea. Se ignoran al dibujar.
• Previsualiza mientras escribes. Una flecha o un corchete que falte rompe todo el diagrama, así que una vista previa en directo ahorra muchas conjeturas. En Markdown Preview Editor el diagrama se vuelve a dibujar mientras editas, y el botón Diagrama Mermaid de la barra del editor avanzado inserta una plantilla inicial.

Compartir documentos con diagramas

Cuando exportas un documento a HTML o PDF, los diagramas se incluyen como imágenes, así que el lector no necesita tener Mermaid instalado. Para añadir fórmulas junto a tus diagramas, consulta cómo escribir fórmulas matemáticas en Markdown, y para todo lo demás —tablas, listas de tareas, avisos— ten a mano la chuleta de Markdown.