Diagrammi Mermaid in Markdown: diagrammi di flusso, di sequenza e altro

I diagrammi spiegano processi, architetture e tempistiche meglio di interi paragrafi di testo. Ma disegnarli in un programma di grafica significa esportare immagini, salvarle accanto alla documentazione e ridisegnare tutto quando qualcosa cambia.

Mermaid risolve il problema: descrivi il diagramma in poche righe di testo all’interno del file Markdown e il visualizzatore lo disegna. Il diagramma vive nello stesso file, compare nei diff e si aggiorna con la stessa facilità di una frase. GitHub, GitLab, Obsidian, molti generatori di documentazione e Markdown Preview Editor visualizzano Mermaid senza configurazioni aggiuntive.

Che cos’è un diagramma Mermaid?

Un diagramma Mermaid è un grafico scritto come testo semplice. Descrivi gli elementi e i collegamenti tra loro, per esempio Login --> Dashboard, e Mermaid calcola la disposizione e disegna l’immagine. Non devi mai posizionare i riquadri a mano: aggiungi una riga e il diagramma si riorganizza da solo.

Il nome viene da Mermaid.js, la libreria open source che si occupa del disegno. Poiché il sorgente è testo, un diagramma Mermaid si può rivedere in una pull request, cercare e modificare come qualsiasi altra parte della documentazione.

Come aggiungere un diagramma Mermaid

Crea un blocco di codice e imposta il linguaggio su mermaid:

markdown```mermaid
flowchart LR
  A[Scrivi] --> B[Anteprima]
  B --> C{Pronto?}
  C -- sì --> D[Esporta]
  C -- no --> A
```

Il visualizzatore lo trasforma in:

La prima riga indica il tipo di diagramma. Tutto ciò che segue descrive nodi e collegamenti.

Diagrammi di flusso

I diagrammi di flusso (flowchart) sono il tipo più usato. La direzione segue la parola chiave: TD o TB (dall’alto in basso), BT, LR (da sinistra a destra) o RL.

mermaidflowchart TD
  start([Inizio]) --> input[/Leggi il file/]
  input --> valid{È valido?}
  valid -- Sì --> save[(Salva nel database)]
  valid -- No --> error[Mostra un errore]
  error --> input

Le parentesi attorno a un’etichetta definiscono la forma del nodo:

Collegamenti: --> è una freccia, --- una linea senza freccia, -.-> una freccia tratteggiata e ==> una freccia spessa. Aggiungi un’etichetta con -- testo --> o -->|testo|.

Raggruppa i nodi correlati con subgraph:

mermaidflowchart LR
  subgraph Browser
    editor[Editor] --> preview[Anteprima]
  end
  preview --> export[HTML / PDF]

Diagrammi di sequenza

I diagrammi di sequenza mostrano come i partecipanti si scambiano messaggi nel tempo: ideali per API, flussi di autenticazione e percorsi utente.

mermaidsequenceDiagram
  participant U as Utente
  participant A as App
  participant S as Server
  U->>A: Clic su "Accedi"
  A->>S: POST /login
  S-->>A: 200 OK + token
  A-->>U: Mostra la dashboard
  Note over A,S: Il token scade dopo 1 ora

->> è una freccia continua (una richiesta), -->> una freccia tratteggiata (una risposta). Note over, Note left of e Note right of aggiungono commenti. Usa i blocchi loop, alt/else e opt per mostrare ripetizioni e diramazioni.

Diagrammi di Gantt

Un diagramma di Gantt trasforma un elenco di attività in una sequenza temporale. Le attività possono iniziare a una data precisa o after (dopo) un’altra attività.

mermaidgantt
  title Sprint di documentazione
  dateFormat YYYY-MM-DD
  section Scrittura
  Scaletta       :done,   a1, 2026-10-01, 2d
  Prima bozza    :active, a2, after a1, 4d
  section Revisione
  Rilettura      :        a3, after a2, 3d
  Pubblicazione  :milestone, after a3, 0d

Diagrammi di stato

I diagrammi di stato descrivono come qualcosa passa da uno stato all’altro: un ordine, un documento, un componente dell’interfaccia.

mermaidstateDiagram-v2
  [*] --> Bozza
  Bozza --> Revisione : invia
  Revisione --> Bozza : modifiche richieste
  Revisione --> Pubblicato : approva
  Pubblicato --> [*]

Grafici a torta

Per un colpo d’occhio sulle proporzioni, un grafico a torta richiede una riga per fetta:

mermaidpie title Dove va il tempo della documentazione
  "Scrittura" : 45
  "Formattazione" : 15
  "Aggiornare i diagrammi" : 40

Mermaid supporta anche diagrammi delle classi, diagrammi entità-relazione, mappe mentali, timeline, grafici Git, grafici a quadranti e altro ancora. La sintassi di ciascuno è documentata sul sito ufficiale di Mermaid.

Consigli per diagrammi leggibili

• Mantienili piccoli. Un diagramma con più di 15–20 nodi diventa difficile da leggere. Dividilo in più diagrammi, uno per idea.
• Scegli la direzione con cura. LR è adatto a processi con pochi passaggi; TD a gerarchie e flussi lunghi, soprattutto su schermi stretti.
• Usa ID brevi ed etichette leggibili. Scrivi auth[Verifica la sessione] invece di usare l’etichetta come ID: i collegamenti restano brevi.
• Metti tra virgolette le etichette con caratteri speciali: A["Prezzo: $5 (IVA incl.)"].
• Aggiungi commenti con %% all’inizio di una riga. Vengono ignorati durante il disegno.
• Guarda l’anteprima mentre scrivi. Una freccia o una parentesi mancante rompe l’intero diagramma, quindi un’anteprima in tempo reale evita molti tentativi alla cieca. In Markdown Preview Editor il diagramma viene ridisegnato mentre modifichi e il pulsante Diagramma Mermaid nella barra Editor avanzato inserisce un modello di partenza. La pagina dell’editor Mermaid ti accompagna nel tuo primo diagramma.

Condividere documenti con diagrammi

Quando esporti un documento in HTML o PDF, i diagrammi vengono inclusi come immagini, quindi il lettore non ha bisogno di Mermaid. Per le formule accanto ai diagrammi, leggi come scrivere formule matematiche in Markdown; per tutto il resto (tabelle, elenchi di attività, avvisi) tieni a portata di mano il cheat sheet Markdown.