Diagramas Mermaid: cómo hacerlos con ejemplos

Los diagramas creados gracias a Mermaid son una bendición. Nadie puede negarlo. Puedes crear diagramas visuales mediante texto. Y lo mejor de todo es que Mermaid está integrado en el programa de toma de notas Obsidian. ¿Lo sabías?

Estos diagramas Mermaid son especialmente interesantes si quieres visualizar relaciones o hacer que tus ideas cobren vida. Y solo tienes que estudiarte un poco cómo funciona su sintaxis.

Dónde se escribe y dónde se ve

No hace falta instalar nada para probar. El editor oficial está en mermaid.live: pegas el código a la izquierda y ves el diagrama a la derecha mientras escribes. Para publicar, Mermaid se integra en bastantes sitios sin plugins:

Dónde	Cómo
Obsidian	Bloque de código con la etiqueta `mermaid`
GitHub	Igual, en cualquier `.md` de un repositorio
Notion	Bloque de código, lenguaje Mermaid
mermaid.live	Editor oficial, exporta SVG y PNG
VS Code	Con la extensión de Mermaid
Web propia	La librería `mermaid` por CDN y llamada a `mermaid.initialize()`

En todos los casos que funcionan con Markdown el patrón es el mismo: tres comillas invertidas, la palabra mermaid, el código, y otras tres comillas para cerrar.

¿Qué tipos de gráficos puedes poner?

¡Ojo! Antes de meter el texto en la nota de Obsidian, puedes jugar con él en mermaid-js.github.io/mermaid-live-editor. Es el editor oficial. Pero puedes usar también mermaidchart.com para guardar tus trabajos.

Tienes diagramas secuenciales, Gantt, líneas de tiempo, Kanban, XY, relacionales, cuadrantes, diagramas de estado… Hay muchos diferentes, pero me gustan especialmente dos tipos:

Flowchart (y Graph)

Puedes crear un diagrama Flowchart que crea conexiones que indican el flujo de un proceso (aquí puedes consultar toda la sintaxis que puedes cambiar para poner diferentes tipos de figuras, flechas y demás), tienes que poner lo siguiente (recuerda que tienes que poner siempre este código entre la llamada a Mermaid del principio):


flowchart LR
    E[Inicio] --> F["¿Se completaron todas las tareas a tiempo?"]
    F --Sí--> G[Ejecutar evento]
    F --No--> H["Reasignar tareas o ajustar el cronograma"]
    H --> E

Y sale algo como esto:

Como puedes comprobar, la sintaxis es bastante sencilla. Puedes cambiar las líneas y las formas. La dirección se cambia con dos letras:

Dirección	Qué hace
`TD` o `TB`	De arriba abajo (por defecto)
`LR`	De izquierda a derecha
`BT`	De abajo arriba
`RL`	De derecha a izquierda

En mermaidchart.com tienes una interfaz más clara y puedes guardar los gráficos. Aquí tienes un ejemplo diagrama Graph para representar relaciones generales entre nodos, sin una secuencia predeterminada:

graph TD;
    A((Inicio)) --> B[/Entrada de datos/]
    B --> C[Procesar datos]
    C --> D{¿Condición?}
    D -- Sí --> E[Acción positiva]
    D -- No --> F[Otra acción]
    E --> G((Fin))
    F --> G

Diferentes formas en el diagrama de Mermaid.

Forma	Ejemplo en Mermaid	Uso
Óvalo	`A((Inicio/Fin))`	Inicio/Fin
Rectángulo	`B[Proceso]`	Proceso/Tarea
Rombo	`C{Decisión}`	Condición
Paralelogramo	`D[/Entrada/Salida/]`	Entrada/Salida
Subrutina	`E[[Subproceso]]`	Llamado a subproceso
Círculo	`F((Nodo circular))`	Representación extra

También puedes usar diferentes tipos de flechas:

Flecha	Se escribe
Normal	`A --> B`
Sin punta	`A --- B`
Con texto	`A -->\\|Sí\\| B`
Punteada	`A -.-> B`
Gruesa	`A ==> B`

También puedes aplicar diferentes colores a tus formas y flechas añadiendo las siguientes líneas:

classDef azul stroke:#1E90FF,stroke-width:2px;

classDef rojo stroke:#FF4500,stroke-width:2px;

classDef verde stroke:#32CD32,stroke-width:2px;

classDef morado stroke:#800080,stroke-width:2px;

classDef dorado stroke:#FFD700,stroke-width:2px;

classDef gris stroke:#808080,stroke-width:2px;

classDef rosa stroke:#FF69B4,stroke-width:2px;

classDef negro stroke:#000000,stroke-width:2px;

classDef cian stroke:#00CED1,stroke-width:2px;

classDef marron stroke:#8B4513,stroke-width:2px;

classDef naranja stroke:#FFA500,stroke-width:2px;

Quedando así el diagrama y su código:

graph TD;
    A((Inicio/Fin)):::azul
    B[Proceso]:::rojo
    C{Decisión}:::verde
    D[/Entrada/Salida/]:::morado
    E[[Subproceso]]:::dorado
    F((Nodo circular)):::gris

    A --> B
    B --> C
    C -- Sí --> D
    C -- No --> E
    D --> F
    E --> F

    classDef azul stroke:#1E90FF,stroke-width:2px;
    classDef rojo stroke:#FF4500,stroke-width:2px;
    classDef verde stroke:#32CD32,stroke-width:2px;
    classDef morado stroke:#800080,stroke-width:2px;
    classDef dorado stroke:#FFD700,stroke-width:2px;
    classDef gris stroke:#808080,stroke-width:2px;

Diferentes formas y colores en el diagrama de Mermaid.

Las posibilidades son infinitas. Es cuestión de ir jugando un poco con la sintaxis.

Mindmap (mapa conceptual)

Me encanta esta opción, Mindmap, porque es muy sencilla de implementar. Solo tienes que ir cambiando la tabulación de los nodos.


mindmap
  root(Inicio)
    Tema1 )Tema 1(
      Desarrollo tema 1
        anexo tema 1
    Tema2 )Tema 2(
      Desarrollo tema 2
        anexo tema 2
    Tema3 )Tema 3(
      Desarrollo tema 3
        anexo tema 3

Solo tienes que cambiar las tabulaciones para modificar las relaciones. También puedes modificar la forma de las figuras cambiando los símbolos. Yo he cambiado en este diagrama las () por )( para poner nubes. Aquí tienes más formas que puedes aplicar:

mindmap
    Formas
        Predeterminado
        [Cuadrado]
        (Redondeado)
        ((Círculo))
        ))Explosión((
        )Nube(
        {{Hexágono}}

Diferentes formas en el diagrama mindmap de Mermaid.

¿Quieres hacerlo más complicado? Puedes hacer algo así:

mindmap
  root(Inicio)
    Tema1 )Tema 1(
      Desarrollo tema 1
        anexo tema 1
        ejemplo tema 1
        aplicación tema 1
      Relación con otros temas
        conexión con tema 2
        conexión con tema 3
    Tema2 )Tema 2(
      Desarrollo tema 2
        anexo tema 2
        caso práctico tema 2
        implicaciones tema 2
      Relación con otros temas
        conexión con tema 1
        conexión con tema 3
    Tema3 )Tema 3(
      Desarrollo tema 3
        anexo tema 3
        variaciones tema 3
        perspectivas tema 3
      Relación con otros temas
        conexión con tema 1
        conexión con tema 2

La sintaxis es muy sencilla. Perfecta para usar directamente en Obsidian y no complicarte mucho la vida. En cuanto te sales del modo edición y pasas al modo de lectura, puedes ver el gráfico.

Te puede interesar leer Mi configuración de Obsidian o Cómo usar Obsidian y MkDocs para publicar tu web online.

¿Más gráficos? Diagrama de Gantt (cronograma), Diagrama de estados de Secuencia

El diagrama de Gantt sirve para planificar un proyecto en el tiempo: qué tareas hay, cuánto duran y en qué orden van. Se declara con gantt.

Diagrama de Gantt (cronograma) con Mermaid

gantt
    title Lanzamiento del sitio
    dateFormat YYYY-MM-DD
    section Diseño
    Bocetos        :a1, 2026-11-02, 10d
    Maqueta final  :a2, after a1, 5d
    section Desarrollo
    Programación   :b1, after a2, 20d
    Contenido      :b2, after a2, 15d
    section Cierre
    Pruebas        :c1, after b1, 7d
    Publicación    :milestone, m1, 2026-12-20, 0d

Tres cosas que hay que entender de la sintaxis:

dateFormat define cómo se escriben las fechas de entrada. Por defecto es YYYY-MM-DD.
Cada tarea lleva dos puntos y después sus datos, separados por comas. Los dos primeros datos
opcionales son etiquetas (done, active, crit, milestone).
after a1 significa «empieza cuando acabe la tarea a1». Es más cómodo que poner fechas a mano,
porque si mueves una tarea las demás se recolocan.

Las duraciones se escriben con un número y una unidad: 10d (días), 2w (semanas), 4h (horas),
1M (meses).

El diagrama de estados representa un sistema que pasa por estados finitos: los estados posibles, qué provoca cada cambio y dónde empieza y acaba. Se declara con stateDiagram-v2.

stateDiagram-v2
    [*] --> Borrador
    Borrador --> Revision: enviar
    Revision --> Borrador: devolver
    Revision --> Publicado: aprobar
    Publicado --> [*]: archivar

[*]Es el punto de inicio cuando apunta hacia fuera y el de fin cuando apunta hacia dentro. El texto después de los dos puntos es la condición que provoca la transición.

El diagrama de secuencia sirve para mostrar el orden en que varios actores se intercambian mensajes. Es el diagrama de las llamadas a una API, de un inicio de sesión o de cualquier conversación entre partes.

Se declara con sequenceDiagram. Los actores se declaran con participant y se les puede poner alias con as.

sequenceDiagram
    participant N as Navegador
    participant S as Servidor
    participant B as Base de datos
    N->>S: GET /articulo/12
    S->>B: SELECT del artículo
    B-->>S: Fila
    S-->>N: HTML de la página

La diferencia entre ->> y -->> es el tipo de línea: la primera es continua y se usa para peticiones; la segunda es discontinua y se usa para respuestas.

Los bloques permiten representar condiciones y bucles:

Bloque	Se escribe
Bucle	`loop Cada minuto` … `end`
Alternativa	`alt Hay datos` … `else No hay` … `end`
Opcional	`opt Si hay sesión` … `end`
Paralelo	`par Tarea A` … `and Tarea B` … `end`
Nota	`Note over N,S: texto`

¿Cómo podemos incluir un diagrama Mermaid en Obsidian?

Muy sencillo. Solo tienes que poner al principio de la nota tres comillas seguidas de la palabra mermaid y terminar el documento con 3 comillas.

Y ahora solo tienes que poner el texto del gráfico entre las comillas. Tienes más referencias en help.obsidian.md. Esta orden sirve también en editores Markdown como el de GitHub.

Los tres errores que rompen un diagrama

Mermaid es estricto con la estructura y blando con los parámetros. Un parámetro mal escrito puede fallar en silencio, pero una palabra desconocida rompe el diagrama entero.

La palabra end dentro de un nodo. Si necesitas escribir «end» en un flowchart o en un diagrama de secuencia, ponlo en mayúsculas (End, END) o entre comillas ("end"). En minúsculas suelta, rompe el diagrama.
Olvidar la primera línea. El tipo de diagrama es obligatorio. Si empiezas directamente por los nodos, no se dibuja nada.
La sangría en el mindmap. En el mindmap la jerarquía es la sangría, así que una línea mal indentada cambia el árbol. Si un nodo aparece donde no toca, mira los espacios de esa línea.

Preguntas frecuentes

¿Mermaid es gratis?
Sí. Es software libre con licencia MIT. El editor oficial, mermaid.live, también es gratis y no requiere cuenta.

¿Se puede usar fuera de Markdown?
Sí. Se integra en páginas web con la librería por CDN, y hay extensiones para VS Code, además de soporte nativo en Obsidian, GitHub y Notion.

¿Puedo exportar el diagrama como imagen?
Desde mermaid.live se descarga en SVG o PNG. El SVG es mejor si vas a imprimir o ampliar, porque no pierde nitidez.

¿Cuántos tipos de diagrama hay?
Bastantes más de los que recoge este artículo: también hay diagramas de entidad-relación, de casos de uso, de requisitos, gráficos circulares, líneas de tiempo y bloques. Para empezar, con los seis de aquí se cubre la mayoría de lo que hace falta.

¿Funciona en WordPress?
No de serie. Hace falta un plugin o insertar la librería. Si el sitio no lo tiene, el bloque se ve como texto.

Conclusión

Es sencillo comenzar a realizar diagramas Mermaid y su sintaxis no es muy complicada. Son una fuente muy importante para entender tus notas en Obsidian o para mejorar tu entendimiento de determinados temas.

¿Tienes más trucos que puedas compartir con todos? Me interesa saber algo más.