Hoja de trucos de sintaxis mermaid

El diagrama más corto que funciona

Un flowchart necesita una línea de declaración y una flecha. TD significa de arriba hacia abajo; usa LR para izquierda a derecha, que se adapta mejor a procesos anchos.

flowchart TD
  A[Start] --> B{Ready?}
  B -->|Yes| C[Ship it]
  B -->|No| A

A, B y C son ids de nodo — nombres internos que nunca se dibujan. El texto entre corchetes es la etiqueta, y el estilo de los corchetes es lo que elige la forma.

Formas de nodo

La forma se elige según el par de delimitadores alrededor de la etiqueta. Estas son las que vale la pena recordar:

💡Pon la etiqueta entre comillas cuando contenga corchetes, dos puntos o comillas: A["Load (raw) data"]. Sin comillas, el analizador interpreta tu puntuación como sintaxis.

Flechas

La longitud de la flecha también tiene significado: --> es un rango, ---> empuja el destino un rango más abajo. Es el control de diseño más simple que mermaid te da.

Agrupar con subgrafos

Un subgraph dibuja una caja etiquetada alrededor de nodos. Los subgrafos se anidan, y las flechas pueden cruzar sus bordes libremente.

flowchart LR
  subgraph api["API"]
    H[Handler] --> S[(Postgres)]
  end
  subgraph worker["Worker"]
    Q[Queue] --> W[Job]
  end
  H --> Q

Color y estilos

style pinta un nodo. classDef más class pinta un conjunto de ellos, que es lo que quieres a partir de tres o cuatro nodos.

flowchart TD
  A[OK] --> B[Failed]
  style A fill:#16a34a,stroke:#333,color:#fff
  classDef bad fill:#dc2626,stroke:#333,color:#fff
  class B bad

Los colores forman parte del código fuente del diagrama, así que sobreviven a la exportación y viajan con el archivo. Nada aquí depende de un ajuste de tema en la herramienta que lo renderiza.

Un ejemplo por cada tipo de diagrama

Diagrama de secuencia

sequenceDiagram
  participant User
  participant API
  participant DB
  User->>API: request
  API->>DB: query
  DB-->>API: rows
  API-->>User: response

Diagrama de clases

classDiagram
  class Animal {
    +String name
    +move()
  }
  class Dog {
    +bark()
  }
  Animal <|-- Dog

Diagrama de estados

stateDiagram-v2
  [*] --> Idle
  Idle --> Running: start
  Running --> Idle: stop
  Running --> [*]: finish

Diagrama de relación de entidades

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  CUSTOMER {
    string name
    string email
  }

Diagrama de Gantt

gantt
  title Project
  dateFormat YYYY-MM-DD
  section Phase 1
  Task 1 :a1, 2026-01-01, 5d
  Task 2 :after a1, 5d

Dónde se renderiza mermaid por sí solo

• GitHub — un bloque ```mermaid con delimitadores se renderiza en issues, pull requests, comentarios y archivos README.
• GitLab — el mismo bloque con delimitadores, en issues, merge requests y la wiki.
• Notion — un bloque de código con el lenguaje configurado en Mermaid se renderiza junto al código fuente.
• Obsidian — un bloque mermaid con delimitadores se renderiza en modo de vista previa.
• Sitios de documentación — Docusaurus, MkDocs Material y VitePress admiten todos los bloques mermaid.

Esa es la verdadera razón para mantener los diagramas como mermaid en lugar de como imágenes: el diagrama vive en el mismo archivo de texto que lo que describe, y una revisión de código puede ver qué cambió en él.