Diagramas con Mermaid en Markdown

Si alguna vez has intentado incluir un diagrama en tu documentación, sabes lo tedioso que puede ser: abrir una aplicación de diseño, crear el gráfico, exportarlo como imagen, subirlo al repositorio y enlazarlo en el Markdown. Cualquier cambio implica repetir todo el proceso. Mermaid elimina ese problema por completo, permitiéndote definir diagramas directamente como texto dentro de tus archivos Markdown. Escribes la estructura del diagrama con una sintaxis sencilla y la herramienta se encarga de renderizarlo automáticamente.

Qué es Mermaid

Mermaid es un lenguaje de definición de diagramas basado en texto. En lugar de arrastrar cajas y flechas con el ratón, describes las relaciones entre elementos usando palabras y símbolos. Mermaid interpreta esa descripción y genera el gráfico visual por ti. Para usarlo en Markdown, solo necesitas un bloque de código con el identificador mermaid:

```mermaid
graph LR
    A --> B --> C
```

En este ejemplo mínimo, graph LR le indica a Mermaid que cree un diagrama de flujo en dirección de izquierda a derecha (left to right). Las letras A, B y C son los nodos, y las flechas --> representan las conexiones entre ellos. El resultado es un diagrama con tres cajas conectadas en línea. Si copias este bloque en un archivo Markdown de GitHub, verás el diagrama renderizado automáticamente.

Dónde funciona Mermaid

Antes de ponerte a escribir diagramas, es importante saber dónde van a funcionar. No todas las plataformas soportan Mermaid de forma nativa, así que conviene verificar la compatibilidad con tu entorno de trabajo.

Si tu plataforma no aparece en la lista, puedes usar el editor en línea de Mermaid para diseñar el diagrama y luego exportarlo como imagen SVG o PNG.

Diagramas de flujo

Los diagramas de flujo son probablemente el tipo de diagrama que más vas a usar. Sirven para representar procesos paso a paso, árboles de decisión o cualquier flujo lógico. En Mermaid se definen con la palabra clave graph o flowchart, seguida de una dirección que indica cómo se distribuyen los nodos:

La dirección más habitual es TD (de arriba a abajo), que es la que usamos por defecto cuando queremos representar un proceso secuencial. Para flujos horizontales, como pipelines o timelines, LR suele funcionar mejor.

Formas de nodo

Cada nodo en un diagrama de flujo puede tener una forma distinta, y esa forma comunica información visual al lector. Por ejemplo, un rombo indica una decisión, un cilindro representa una base de datos, y un rectángulo es un paso genérico del proceso. La forma se define con los caracteres que rodean al texto del nodo:

```mermaid
flowchart TD
    A[Rectángulo]
    B(Redondeado)
    C([Estadio])
    D[[Subrutina]]
    E{Rombo / Decisión}
    F{{Hexágono}}
    G>Bandera]
    H[(Base de datos)]
```

No necesitas memorizar todas las formas de golpe. Lo más práctico es empezar con rectángulos ([texto]) y rombos ({texto}) para decisiones, e ir incorporando las demás a medida que las necesites.

Tipos de conexión

Los nodos por sí solos no dicen mucho; lo importante son las conexiones entre ellos. Mermaid ofrece varios tipos de flecha para representar distintas relaciones. Una flecha sólida indica un flujo directo, una punteada sugiere una relación más débil o condicional, y una gruesa destaca un camino principal. Además, puedes añadir texto sobre cualquier flecha para describir la relación:

```mermaid
flowchart LR
    A --> B
    A --- C
    A -.-> D
    A ==> E
    A -->|texto| F
    A -- texto --> G
```

Ejemplo práctico: flujo de CI/CD

Veamos un caso real para que todo lo anterior cobre sentido. Este diagrama representa un pipeline típico de integración continua: cuando alguien hace push a la rama principal, se ejecutan los tests y, dependiendo del resultado, se despliega o se notifica el fallo. Fíjate en cómo el rombo {Tests pasan?} crea una bifurcación con dos caminos posibles, cada uno etiquetado con Sí o No:

```mermaid
flowchart TD
    A[Push a main] --> B[GitHub Actions]
    B --> C[Instalar dependencias]
    C --> D[Ejecutar tests]
    D --> E{Tests pasan?}
    E -->|Sí| F[Build]
    E -->|No| G[Notificar fallo]
    F --> H[Deploy a producción]
    G --> I[Crear issue]
```

Este tipo de diagrama es ideal para incluir en el README de un proyecto, ya que cualquier persona del equipo puede entender el proceso de despliegue de un vistazo. Además, al estar definido como texto, se actualiza con un simple commit, sin necesidad de rehacer una imagen.

Subgrafos

Los subgrafos agrupan nodos relacionados dentro de una caja visual, lo que resulta especialmente útil cuando tu diagrama tiene componentes lógicos diferenciados, como frontend y backend:

```mermaid
flowchart TB
    subgraph Frontend
        A[React] --> B[Next.js]
    end
    subgraph Backend
        C[Node.js] --> D[PostgreSQL]
    end
    B --> C
```

Cada subgraph se renderiza como una caja que agrupa visualmente sus nodos, y las conexiones entre subgrafos (como B --> C) se muestran como flechas que cruzan de una caja a otra. Puedes anidar subgrafos dentro de otros subgrafos para representar jerarquías más complejas.

Diagramas de secuencia

Los diagramas de secuencia muestran cómo interactúan distintos componentes a lo largo del tiempo, representando cada mensaje o llamada como una flecha entre participantes. Son perfectos para documentar flujos de autenticación, peticiones HTTP o cualquier proceso donde importa el orden de las comunicaciones.

En el siguiente ejemplo se muestra el flujo completo de un formulario: desde que el usuario lo envía hasta que recibe la confirmación, pasando por el frontend, la API y la base de datos:

```mermaid
sequenceDiagram
    participant U as Usuario
    participant F as Frontend
    participant A as API
    participant D as Base de datos

    U->>F: Envía formulario
    F->>A: POST /api/users
    A->>D: INSERT INTO users
    D-->>A: OK
    A-->>F: 201 Created
    F-->>U: Muestra confirmación
```

Observa cómo cada participante se define con participant y un alias corto (como U para Usuario). Esto hace que las líneas de interacción sean más compactas y fáciles de leer.

Tipos de flecha

Elegir el tipo de flecha correcto ayuda a transmitir la naturaleza de cada comunicación:

Bloques de lógica

Los diagramas de secuencia se vuelven realmente expresivos cuando añades lógica condicional y anotaciones:

Notas

Las notas se colocan con Note left of, Note right of o Note over (este último acepta varios participantes separados por coma):

```mermaid
sequenceDiagram
    participant C as Cliente
    participant S as Servidor

    C->>S: Login
    Note over C,S: Credenciales cifradas con TLS
    Note right of S: Valida contra BBDD
    S-->>C: Token JWT
```

Ejemplo con lógica condicional

Este ejemplo modela un flujo de autenticación con JWT. El bloque alt muestra claramente las dos ramas del flujo de login, y la nota sobre ambos participantes recuerda un detalle importante de implementación:

```mermaid
sequenceDiagram
    participant C as Cliente
    participant S as Servidor

    C->>S: Login (usuario, password)

    alt Credenciales válidas
        S-->>C: Token JWT
    else Credenciales inválidas
        S-->>C: Error 401
    end

    Note over C,S: El token expira en 24h

    loop Cada petición
        C->>S: Request + Token
        S-->>C: Response
    end
```

Si pegas este código en un README, cualquier desarrollador nuevo en el equipo entenderá el flujo de autenticación sin necesidad de leer el código fuente.

Diagramas de Gantt

Los diagramas de Gantt no representan flujos técnicos, sino planificación temporal. Son ideales para incluir en documentos de proyecto, propuestas o wikis de equipo. Mermaid genera las barras de tiempo automáticamente a partir de las fechas y duraciones que indiques, e incluso puede excluir fines de semana del cálculo:

```mermaid
gantt
    title Plan de desarrollo Q1 2026
    dateFormat YYYY-MM-DD
    excludes weekends

    section Backend
    Diseñar API           :a1, 2026-01-05, 5d
    Implementar endpoints :a2, after a1, 10d
    Tests de integración  :a3, after a2, 5d

    section Frontend
    Diseñar UI            :b1, 2026-01-05, 7d
    Implementar vistas    :b2, after b1, 12d
    Tests E2E             :b3, after b2, 3d

    section Deploy
    Configurar CI/CD      :c1, after a3, 3d
    Deploy a staging      :c2, after c1, 2d
    Deploy a producción   :milestone, after c2, 0d
```

Fíjate en algunos detalles importantes: dateFormat define el formato de las fechas, excludes weekends descuenta sábados y domingos, y la palabra after permite encadenar tareas sin calcular fechas manualmente. Las secciones (section) agrupan las tareas visualmente, lo que facilita ver qué hace cada equipo en paralelo.

Estados de tareas

Puedes marcar el estado de cada tarea añadiendo un modificador después del identificador. Esto cambia el aspecto visual de la barra en el diagrama:

Se pueden combinar: Corregir bug :crit, active, 2026-01-15, 3d.

Dependencias

Usa after id_tarea para encadenar tareas sin calcular fechas manualmente. Mermaid calcula las fechas de inicio automáticamente. El dateFormat acepta tokens de Day.js: YYYY-MM-DD, DD/MM/YYYY, etc.

Diagramas de clases

Si trabajas con programación orientada a objetos, los diagramas de clases te permiten documentar la estructura de tu código de forma visual: clases, atributos, métodos y las relaciones entre ellas. Son especialmente útiles en la documentación técnica de librerías o en guías de arquitectura:

```mermaid
classDiagram
    class Animal {
        +String nombre
        +int edad
        +comer()
        +dormir()
    }

    class Perro {
        +String raza
        +ladrar()
    }

    class Gato {
        +bool domestico
        +maullar()
    }

    Animal <|-- Perro
    Animal <|-- Gato
```

En este diagrama, Animal es la clase padre con atributos comunes (nombre, edad) y métodos generales (comer(), dormir()). Las clases Perro y Gato heredan de Animal y añaden sus propios atributos y métodos específicos. La flecha <|-- indica la relación de herencia. Los signos + delante de cada miembro indican que son públicos.

Visibilidad de miembros

Relaciones entre clases

Las relaciones entre clases se expresan con distintos tipos de flecha, cada una con un significado específico en UML:

Si no estás familiarizado con UML, no te agobies. Para la mayoría de documentaciones basta con herencia (<|--) y asociación (-->). Se puede añadir cardinalidad a las relaciones: A "1" --> "*" B : tiene.

Diagramas de estado

Los diagramas de estado son perfectos cuando necesitas documentar el ciclo de vida de una entidad: por ejemplo, los estados posibles de un pedido, un ticket de soporte o un artículo en un CMS. Cada nodo representa un estado y las flechas indican las transiciones posibles, etiquetadas con la acción que las provoca:

```mermaid
stateDiagram-v2
    [*] --> Borrador
    Borrador --> EnRevisión: Enviar
    EnRevisión --> Aprobado: Aprobar
    EnRevisión --> Borrador: Rechazar
    Aprobado --> Publicado: Publicar
    Publicado --> Archivado: Archivar
    Archivado --> [*]
```

El símbolo especial [*] representa el punto de inicio y el punto final del diagrama. En este caso, el flujo empieza en Borrador y termina cuando el contenido se archiva. Observa cómo la transición de EnRevisión puede ir hacia Aprobado (si se aprueba) o de vuelta a Borrador (si se rechaza), lo que refleja un ciclo de revisión realista.

Estados compuestos

Puedes anidar estados dentro de otros para representar subestados. Esto es útil cuando un estado tiene su propia lógica interna:

```mermaid
stateDiagram-v2
    [*] --> Activo
    state Activo {
        [*] --> Trabajando
        Trabajando --> Pausado: Pausar
        Pausado --> Trabajando: Reanudar
    }
    Activo --> Completado: Finalizar
    Completado --> [*]
```

Bifurcaciones (fork/join)

Para flujos que se dividen en tareas paralelas y vuelven a unirse:

```mermaid
stateDiagram-v2
    state fork_state <<fork>>
    state join_state <<join>>

    [*] --> fork_state
    fork_state --> Tarea1
    fork_state --> Tarea2
    Tarea1 --> join_state
    Tarea2 --> join_state
    join_state --> [*]
```

Diagramas entidad-relación (ER)

Si trabajas con bases de datos, los diagramas ER (entidad-relación) son imprescindibles para documentar el modelo de datos. Mermaid te permite definir las tablas con sus columnas, tipos de dato, claves primarias y foráneas, además de las relaciones entre ellas con su cardinalidad:

```mermaid
erDiagram
    USUARIO ||--o{ PEDIDO : "realiza"
    PEDIDO ||--|{ LINEA_PEDIDO : "contiene"
    PRODUCTO ||--o{ LINEA_PEDIDO : "aparece en"

    USUARIO {
        int id PK
        string nombre
        string email UK
        date creado_en
    }
    PEDIDO {
        int id PK
        date fecha
        float total
        int usuario_id FK
    }
    PRODUCTO {
        int id PK
        string nombre
        float precio
        int stock
    }
    LINEA_PEDIDO {
        int id PK
        int pedido_id FK
        int producto_id FK
        int cantidad
    }
```

En la definición de relaciones, la parte entre comillas ("realiza", "contiene") describe la naturaleza de la relación en lenguaje natural. Las marcas PK, FK y UK junto a las columnas identifican las claves primarias, foráneas y únicas, lo que hace que el diagrama sea autoexplicativo.

Cardinalidades

La cardinalidad define cuántos registros de una tabla se relacionan con cuántos de otra. Mermaid usa una notación visual con barras y círculos:

El círculo o indica que la relación es opcional (puede ser cero), mientras que la barra | indica que es obligatoria (al menos uno).

Diagramas de pastel

Los diagramas de pastel son los más sencillos de crear en Mermaid. Son útiles para mostrar proporciones o distribuciones de datos de un vistazo. Solo necesitas un título y una lista de etiquetas con sus valores numéricos; Mermaid se encarga de calcular los porcentajes y asignar los colores:

```mermaid
pie title Lenguajes más usados en 2026
    "JavaScript" : 30
    "Python" : 25
    "TypeScript" : 18
    "Java" : 12
    "Go" : 8
    "Otros" : 7
```

Ten en cuenta que los diagramas de pastel no son la mejor opción para datos complejos o comparaciones precisas. Úsalos cuando quieras dar una visión general rápida, como en un resumen ejecutivo o una presentación informal.

Mapas mentales

Los mapas mentales son una adición relativamente reciente a Mermaid, y resultan muy útiles para organizar ideas, planificar el contenido de un documento o hacer brainstorming. La estructura se define mediante indentación: cada nivel de sangría crea una rama más profunda en el mapa:

```mermaid
mindmap
  root((Markdown))
    Sintaxis
      Básica
      Extendida
      Avanzada
    Herramientas
      Editores
      Conversores
      Generadores
    Usos
      Documentación
      Blogs
      Notas
      IA
```

La belleza de este formato es su simplicidad: no hay flechas, ni llaves, ni símbolos especiales. Solo texto e indentación. Es una forma excelente de empezar a usar Mermaid si nunca lo has probado antes.

Timeline

Para representar eventos cronológicos de forma visual. Cada línea define un momento en el tiempo con su descripción:

```mermaid
timeline
    title Historia de Markdown
    2004 : John Gruber crea Markdown
    2012 : GitHub Flavored Markdown
    2014 : Especificación CommonMark
    2016 : Mermaid 1.0
    2022 : GitHub soporta Mermaid nativo
    2024 : Mermaid 11.0
```

Es una forma visual y compacta de documentar la evolución de un proyecto, los hitos de un producto o la cronología de cualquier proceso.

Quadrant Chart

Los quadrant charts permiten clasificar elementos en una matriz de dos ejes. Son muy utilizados en gestión de producto para priorización (esfuerzo vs impacto) o en análisis competitivo:

```mermaid
quadrantChart
    title Priorización de tareas
    x-axis Bajo esfuerzo --> Alto esfuerzo
    y-axis Bajo impacto --> Alto impacto
    quadrant-1 Hacer ya
    quadrant-2 Planificar
    quadrant-3 Delegar
    quadrant-4 Eliminar
    Corregir typos: [0.2, 0.3]
    Actualizar docs: [0.3, 0.7]
    Añadir dark mode: [0.7, 0.4]
    Refactorizar auth: [0.8, 0.9]
```

Los valores entre corchetes son coordenadas de 0 a 1 que posicionan cada elemento en la matriz. Esto genera un gráfico donde se puede ver de un vistazo qué tareas priorizar.

Git Graph

Para visualizar ramas, commits y merges de Git de forma gráfica. Es ideal para documentar estrategias de branching como Git Flow o trunk-based development:

```mermaid
gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    branch feature
    checkout feature
    commit
    checkout main
    merge feature
```

Cada línea define una acción de Git (commit, branch, checkout, merge) y Mermaid genera automáticamente el gráfico con las ramas y las líneas de conexión.

Diagrama de requisitos

Para documentar requisitos de software y sus relaciones con los elementos que los satisfacen. Es útil en documentación formal o en proyectos que siguen metodologías como RUP:

```mermaid
requirementDiagram
    requirement Login {
        id: REQ-001
        text: El usuario debe poder iniciar sesión
        risk: high
        verifymethod: test
    }
    element app_login {
        type: módulo
    }
    app_login - satisfies -> Login
```

Personalización

Una vez que domines la estructura de los diagramas, puedes darles un toque visual más acorde con tu proyecto o marca. Mermaid ofrece dos formas principales de personalización: temas predefinidos y estilos CSS personalizados.

Temas

Mermaid incluye cuatro temas integrados que cambian la paleta de colores y el estilo general del diagrama:

Para aplicar un tema, añade una directiva de configuración al inicio del bloque:

```mermaid
%%{init: {'theme': 'forest'}}%%
graph LR
    A --> B --> C
```

La línea %%{init: {'theme': 'forest'}}%% es una directiva especial de Mermaid (los %% indican un comentario en Mermaid, pero init es un comentario especial que configura el renderizado). Prueba los distintos temas en mermaid.live para ver cuál encaja mejor con tu documentación.

Estilos CSS personalizados

Si los temas predefinidos no son suficientes, puedes definir clases CSS personalizadas con classDef. Esto te permite asignar colores específicos a nodos individuales, lo cual es útil para destacar estados (éxito en verde, error en rojo, proceso en azul):

```mermaid
flowchart LR
    A[OK]:::verde --> B[Proceso]:::azul --> C[Error]:::rojo

    classDef verde fill:#d4edda,stroke:#28a745
    classDef azul fill:#cce5ff,stroke:#007bff
    classDef rojo fill:#f8d7da,stroke:#dc3545
```

Cada classDef recibe un nombre (como verde, azul, rojo) y las propiedades CSS que quieres aplicar (fill para el color de fondo, stroke para el borde). Luego asignas la clase a un nodo con la sintaxis :::nombreClase.

Configuración avanzada

Puedes ajustar parámetros específicos de cada tipo de diagrama con la directiva init, incluyendo colores personalizados para que el diagrama encaje con la identidad visual de tu proyecto:

```mermaid
%%{init: {
  'theme': 'default',
  'themeVariables': {
    'primaryColor': '#9333ea',
    'primaryTextColor': '#fff',
    'lineColor': '#06b6d4'
  }
}}%%
graph LR
    A --> B --> C
```

Comentarios

Usa %% para añadir comentarios que no se renderizan en el diagrama final. Son útiles para documentar diagramas complejos o dejar notas para otros miembros del equipo:

```mermaid
graph TD
    %% Este es un comentario
    A --> B
    %% Aquí empieza la bifurcación
    B --> C
    B --> D
```

Consejos prácticos

Para cerrar esta guía, aquí tienes una serie de recomendaciones basadas en la experiencia de trabajar con Mermaid en proyectos reales:

1. Empieza simple: Define los nodos primero, luego las conexiones.
2. Usa alias cortos: participant U as Usuario hace el código más legible.
3. Divide diagramas grandes: Varios diagramas pequeños son más claros que uno enorme.
4. Prueba en el editor: mermaid.live te permite editar y previsualizar en tiempo real.
5. Usa comentarios: %% esto es un comentario para documentar secciones complejas.
6. Aprovecha subgrafos: Agrupa nodos relacionados con subgraph para crear secciones visuales claras.

Referencia rápida

Si te interesa incluir otros elementos avanzados en tus documentos, consulta la guía de fórmulas matemáticas con KaTeX y MathJax. Para los fundamentos del lenguaje, revisa la sintaxis básica de Markdown. Y si documentas arquitectura o procesos técnicos, la guía de Markdown para desarrolladores te resultará útil.