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.

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.

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.