Cheat sheet della sintassi mermaid

Il diagramma più breve che funziona

Un flowchart richiede una riga di dichiarazione e una freccia. TD significa dall'alto verso il basso; usa LR per la disposizione da sinistra a destra, più adatta ai processi ampi.

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

A, B e C sono id dei nodi — nomi interni, mai disegnati. Il testo tra parentesi è l'etichetta, e lo stile delle parentesi determina la forma.

Forme dei nodi

La forma è scelta dalla coppia di delimitatori attorno all'etichetta. Queste sono quelle da ricordare:

💡Racchiudi l'etichetta tra virgolette quando contiene parentesi, due punti o virgolette: A["Load (raw) data"]. Senza virgolette il parser interpreta la tua punteggiatura come sintassi.

Frecce

La lunghezza della freccia è significativa: --> corrisponde a un livello, ---> sposta la destinazione un livello più in basso. È il controllo di layout più semplice che mermaid offre.

Raggruppare con i sottografi

Un subgraph disegna un riquadro etichettato attorno ai nodi. I sottografi si possono annidare, e le frecce possono attraversarne liberamente i confini.

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

Colore e stile

style colora un singolo nodo. classDef più class colora un insieme di essi, utile oltre i tre o quattro nodi.

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

I colori fanno parte del codice sorgente del diagramma, quindi sopravvivono all'esportazione e viaggiano con il file. Nulla qui dipende da un'impostazione di tema dello strumento che lo renderizza.

Un esempio per ogni tipo di diagramma

Diagramma di sequenza

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

Diagramma delle classi

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

Diagramma di stato

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

Diagramma entità-relazione

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

Diagramma di Gantt

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

Dove mermaid si renderizza da solo

• GitHub — un blocco ```mermaid con recinto si renderizza in issue, pull request, commenti e file README.
• GitLab — lo stesso blocco con recinto, in issue, merge request e nella wiki.
• Notion — un blocco di codice con il linguaggio impostato su Mermaid si renderizza accanto al sorgente.
• Obsidian — un blocco mermaid con recinto si renderizza in modalità anteprima.
• Siti di documentazione — Docusaurus, MkDocs Material e VitePress supportano tutti i blocchi mermaid.

Questo è il vero motivo per mantenere i diagrammi come mermaid invece che come immagini: il diagramma vive nello stesso file di testo di ciò che descrive, e una code review può vedere cosa è cambiato al suo interno.