Guida rapida e cheat sheet per i diagrammi Mermaid per sviluppatori
Diagrammi come codice, senza il caos.
Mermaid è uno strumento di diagrammazione basato su testo, pensato per chi preferisce scrivere i diagrammi piuttosto che trascinare caselle su un canvas. Utilizza una sintassi simile a Markdown per descrivere diagrammi di flusso, diagrammi di sequenza, diagrammi di classe, macchine a stati, linee temporali, diagrammi di Gantt, diagrammi delle relazioni tra entità e molto altro.
Per un blog tecnico, Mermaid è un’ottima scelta predefinita. I diagrammi vivono accanto all’articolo, possono essere revisionati in Git e sono facili da aggiornare quando il sistema cambia. I diagrammi statici in formato immagine hanno un bell’aspetto finché non avviene la prima modifica architetturale. I diagrammi Mermaid non sono perfetti, ma invecchiano molto meglio.
Questa guida è una rapida introduzione pratica e un riferimento sintetico (cheatsheet) per Mermaid, rivolta a sviluppatori, tecnici della scrittura e proprietari di siti Hugo. Fa parte del hub Strumenti di documentazione nel 2026: Markdown, LaTeX, PDF e flussi di lavoro di stampa.
Cos’è Mermaid?
Mermaid è una sintassi “diagram-as-code”. Si scrive un piccolo blocco di testo e Mermaid lo renderizza come un diagramma.
Un diagramma Mermaid di base si presenta così:
questo codice:
```mermaid
flowchart TD
A[Scrivi Markdown] --> B[Aggiungi blocco Mermaid]
B --> C[Renderizza pagina]
C --> D[Pubblica diagramma]
```
Produce questo diagramma:
L’idea fondamentale è semplice: la fonte del diagramma è testo puro. Questo lo rende ricercabile, revisionabile, portatile e facile da mantenere insieme alla documentazione che spiega.
Perché usare Mermaid in un blog tecnico?
Mermaid è utile quando il tuo articolo ha bisogno di più del semplice testo narrativo, ma meno di un completo strumento di design.
Usa Mermaid quando vuoi spiegare:
- Flussi di richiesta e risposta
- Pipeline di deployment
- Dipendenze tra servizi
- Transizioni di stato
- Relazioni tra database
- Percorsi utente (User journeys)
- Fasi di build
- Logica decisionale
- Tempi di progetto
Non userei Mermaid per ogni tipo di visuale. Screenshot, schizzi architetturali fatti a mano e diagrammi di marketing curati al millimetro hanno ancora il loro spazio. Ma per la documentazione ingegneristica, Mermaid è spesso l’opzione più facile da mantenere.
Introduzione rapida a Mermaid
Uso di base in Markdown
In Markdown, usa un blocco di codice delimitato (fenced code block) con mermaid come linguaggio:
```mermaid
flowchart LR
A[Inizio] --> B[Processo]
B --> C[Fine]
```
Molte piattaforme comprendono questo formato direttamente. mermaid è uno degli identificatori di linguaggio speciali — insieme a diff, geojson e altri — che certi renderizzatori trattano come un tipo di blocco di prima classe piuttosto che come semplice evidenziazione della sintassi. Per un’analisi completa della sintassi dei blocchi delimitati e degli identificatori di linguaggio supportati, consulta la guida sui blocchi di codice Markdown. Per Hugo, il rendering dipende dal tuo tema o dalla configurazione del sito. Ne parleremo più avanti.
Testa i diagrammi prima di pubblicare
Il flusso di lavoro più semplice è:
- Scrivi il diagramma nel tuo file Markdown.
- Incollalo in un editor live di Mermaid o in una preview locale.
- Correggi gli errori di sintassi.
- Effettua il commit della sorgente Markdown.
- Controlla la pagina renderizzata finale.
Questo evita il classico problema in cui un diagramma funziona in un renderizzatore ma si rompe in un altro a causa di un piccolo dettaglio sintattico.
Sintassi dei diagrammi di flusso
I diagrammi di flusso sono il tipo di diagramma Mermaid più comune. Usali per flussi di lavoro, algoritmi, alberi decisionali e passaggi di sistema.
Diagramma di flusso di base
questo codice:
```mermaid
flowchart TD
A[L'utente apre il sito web] --> B{L'utente è connesso?}
B -->|Sì| C[Mostra dashboard]
B -->|No| D[Mostra pagina di accesso]
```
Produce questo diagramma:
Direzioni dei diagrammi di flusso
I diagrammi di flusso Mermaid supportano diverse direzioni:
TD - dall'alto al basso
TB - dall'alto al basso
BT - dal basso all'alto
LR - da sinistra a destra
RL - da destra a sinistra
Esempio:
questo codice:
```mermaid
flowchart LR
Browser --> CDN
CDN --> WebServer
WebServer --> Database
```
Produce questo diagramma:
Per gli articoli del blog, LR (da sinistra a destra) è spesso più facile da leggere per i diagrammi architetturali. Per i processi passo-passo, TD (dall’alto al basso) è solitamente migliore.
Forme di nodo comuni
questo codice:
```mermaid
flowchart TD
A[Rettangolo]
B(Rettangolo arrotondato)
C{Decisione}
D((Cerchio))
E[(Database)]
F[[Sottoprogramma]]
```
Produce questo diagramma:
Frecce nei diagrammi di flusso
questo codice:
```mermaid
flowchart LR
A --> B
B --- C
C -.-> D
D ==> E
E -- Etichetta --> F
```
Produce questo diagramma:
Sogragrafi (Subgraphs)
Usa i sottografi per raggruppare parti correlate di un sistema.
questo codice:
```mermaid
flowchart LR
subgraph Client
Browser
end
subgraph Backend
API
Worker
end
subgraph Storage
DB[(PostgreSQL)]
Cache[(Redis)]
end
Browser --> API
API --> DB
API --> Cache
API --> Worker
```
Produce questo diagramma:
I sottografi sono potenti, ma usali con cautela. Un diagramma con sei sottografi e venti frecce è solitamente un segnale che l’articolo ha bisogno di due diagrammi più piccoli.
Sintassi dei diagrammi di sequenza
I diagrammi di sequenza mostrano la comunicazione tra attori o servizi nel tempo.
questo codice:
```mermaid
sequenceDiagram
participant User
participant App
participant API
participant DB
User->>App: Clicca accesso
App->>API: POST /login
API->>DB: Convalida credenziali
DB-->>API: Record utente
API-->>App: Token di accesso
App-->>User: Mostra dashboard
```
Produce questo diagramma:
Frecce comuni nei diagrammi di sequenza
-> linea solida senza freccia
--> linea tratteggiata senza freccia
->> linea solida con freccia
-->> linea tratteggiata con freccia
-x linea solida con croce
--x linea tratteggiata con croce
Barre di attivazione
Le barre di attivazione rendono più chiaro quando un partecipante sta eseguendo un lavoro.
questo codice:
```mermaid
sequenceDiagram
participant Client
participant Server
Client->>Server: Richiedi dati
activate Server
Server-->>Client: Risposta
deactivate Server
```
Produce questo diagramma:
Alternative e condizioni
questo codice:
```mermaid
sequenceDiagram
participant User
participant API
participant Payment
User->>API: Invia ordine
alt Il pagamento ha successo
API->>Payment: Addebita carta
Payment-->>API: Approvato
API-->>User: Ordine confermato
else Il pagamento fallisce
Payment-->>API: Rifiutato
API-->>User: Mostra errore
end
```
Produce questo diagramma:
I diagrammi di sequenza sono eccellenti per gli articoli sulle API. Mostrano non solo quali componenti esistono, ma anche come comunicano tra loro.
Sintassi dei diagrammi di classe
I diagrammi di classe sono utili per i modelli di dominio e le relazioni tra oggetti.
questo codice:
```mermaid
classDiagram
class User {
+string id
+string email
+login()
+logout()
}
class Order {
+string id
+float total
+submit()
}
User "1" --> "*" Order
```
Produce questo diagramma:
Relazioni tra classi
<|-- ereditarietà
*-- composizione
o-- aggregazione
--> associazione
-- collegamento (link)
..> dipendenza
..|> realizzazione
Esempio:
questo codice:
```mermaid
classDiagram
Animal <|-- Dog
Animal <|-- Cat
User "1" --> "*" Order
Order *-- OrderItem
```
Produce questo diagramma:
I diagrammi di classe possono diventare rumorosi rapidamente. In un post sul blog, preferisci una piccola sezione del dominio rispetto a un modello completo dell’applicazione.
Sintassi dei diagrammi di stato
I diagrammi di stato spiegano come qualcosa cambia nel tempo.
questo codice:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Review: submit
Review --> Published: approve
Review --> Draft: request changes
Published --> Archived: archive
Archived --> [*]
```
Produce questo diagramma:
Usa i diagrammi di stato per:
- Cicli di vita degli ordini
- Stati di deployment
- Flussi di autenticazione
- Stato dei job in background
- Flussi di pubblicazione dei contenuti
I diagrammi di stato sono sottovalutati. Spesso spiegano la logica di business meglio di un paragrafo lungo.
Sintassi dei diagrammi delle relazioni tra entità
I diagrammi delle relazioni tra entità sono utili per i modelli di database.
questo codice:
```mermaid
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : appears_in
USER {
string id
string email
}
ORDER {
string id
datetime created_at
}
PRODUCT {
string id
string name
}
```
Produce questo diagramma:
Marcatori di relazione ER
|| esattamente uno
o| zero o uno
}| uno o più
}o zero o più
I diagrammi ER sono migliori quando spiegano le relazioni, non ogni colonna. Mantieni i dettagli di implementazione nelle migrazioni o nella documentazione dello schema.
Sintassi dei diagrammi di Gantt
I diagrammi di Gantt sono utili per le tempistiche di progetto.
questo codice:
```mermaid
gantt
title Piano di migrazione della documentazione
dateFormat YYYY-MM-DD
section Pianificazione
Audit documenti attuali :a1, 2026-06-01, 5d
Definisci struttura :a2, after a1, 3d
section Scrittura
Riscrivi guide :b1, after a2, 10d
Revisiona e pubblica :b2, after b1, 4d
```
Produce questo diagramma:
I diagrammi di Gantt sono utili nei post di pianificazione interna, ma possono invecchiare rapidamente. Usali quando la tempistica stessa è il punto fondamentale.
Sintassi delle linee temporali
Le linee temporali sono buone per le cronologie delle release, i report sugli incidenti e i riassunti di progetto.
questo codice:
```mermaid
timeline
title Evoluzione dell'API
2024 : API REST lanciata
2025 : Aggiunti Webhook
2026 : Introdotto lo streaming degli eventi
```
Produce questo diagramma:
Usa una linea temporale quando l’ordine è più importante della dipendenza. Se ciò che ti interessa è la sequenza degli eventi piuttosto che come si connettono causalmente, una linea temporale mantiene il focus dove dovrebbe essere e rimane facile da leggere a colpo d’occhio.
Sintassi dei diagrammi a torta
I diagrammi a torta sono supportati, ma fai attenzione. Sono facili da leggere quando ci sono solo poche categorie e i valori sono chiaramente diversi.
questo codice:
```mermaid
pie title Tempo di build per fase
"Install dependencies" : 35
"Run tests" : 45
"Build assets" : 20
```
Produce questo diagramma:
Consiglio personale: se i valori sono vicini o ci sono più di cinque categorie, usa una tabella invece. Una tabella ben formattata comunica i numeri precisi in modo più onesto rispetto a un diagramma a torta dove le fette sembrano quasi identiche.
Sintassi dei grafici Git
I grafici Git possono spiegare le strategie di branching e i flussi di release.
questo codice:
```mermaid
gitGraph
commit
branch feature
checkout feature
commit
commit
checkout main
merge feature
commit
```
Produce questo diagramma:
Questo è utile per articoli sui flussi di lavoro Git, sviluppo basato su trunk, rami di release e hotfix. Se hai bisogno di un riferimento rapido per i comandi di branching sottostanti, il Riferimento Git copre quelli più comuni insieme ai flussi di lavoro di merge e rebase.
Riferimento sintetico (Cheatsheet) Mermaid
Tipi di diagramma
flowchart TD
sequenceDiagram
classDiagram
stateDiagram-v2
erDiagram
gantt
timeline
pie
gitGraph
mindmap
journey
Fondamenti dei diagrammi di flusso
flowchart TD
A[Testo] --> B[Testo]
A -->|Etichetta| B
A -.-> B
A ==> B
A --- B
Forme nei diagrammi di flusso
A[Rettangolo]
A(Arrotondato)
A{Decisione}
A((Cerchio))
A[(Database)]
A[[Sottoprogramma]]
A>Bandiera]
Fondamenti dei diagrammi di sequenza
sequenceDiagram
participant A
participant B
A->>B: Messaggio
B-->>A: Risposta
activate B
deactivate B
Blocchi di sequenza
alt condizione
else altra condizione
end
opt passaggio opzionale
end
loop per ogni elemento
end
par task parallelo
and altro task
end
Fondamenti dei diagrammi di classe
classDiagram
class User
class Order
User --> Order
User "1" --> "*" Order
Fondamenti dei diagrammi di stato
stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Done
Done --> [*]
Fondamenti dei diagrammi ER
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
Commenti
Mermaid supporta i commenti con %%.
questo codice:
```mermaid
flowchart TD
%% Questo è un commento
A --> B
```
Produce questo diagramma:
Uso di Mermaid in Hugo
I contenuti Hugo sono solitamente scritti in Markdown, quindi Mermaid si integra naturalmente in un blog tecnico basato su Hugo. La configurazione esatta dipende dal tuo tema e dalla configurazione del rendering Markdown.
Il modello di scrittura comune rimane lo stesso:
```mermaid
flowchart LR
Markdown --> Hugo
Hugo --> HTML
HTML --> Browser
```
Se il tuo tema Hugo supporta già Mermaid, questo potrebbe renderizzarsi senza lavoro aggiuntivo. Se non lo supporta, solitamente hai bisogno di un render hook, shortcode, partial o configurazione del tema che carichi Mermaid sulle pagine contenenti diagrammi Mermaid.
Una configurazione pratica di Hugo dovrebbe puntare a queste regole:
- Mantieni la sorgente Mermaid all’interno degli articoli Markdown normali.
- Carica Mermaid solo sulle pagine che ne hanno bisogno.
- Evita JavaScript globale se la maggior parte delle pagine non usa diagrammi.
- Testa i diagrammi durante la preview locale.
- Mantieni la sorgente del diagramma leggibile in Git.
Per un blog tecnico, i blocchi di codice delimitati sono solitamente migliori degli shortcode personalizzati perché sono più portabili. Se in seguito sposti i contenuti su GitHub, un altro generatore di siti statici o una piattaforma di documentazione, i blocchi Mermaid delimitati standard sono più facili da riutilizzare.
Best Practice per Mermaid
Mantieni i diagrammi piccoli
Un diagramma dovrebbe chiarire l’articolo, non sostituirlo. Se i lettori devono zoomare, il diagramma è probabilmente troppo grande.
I buoni diagrammi solitamente hanno:
- Un’idea unica
- Direzione chiara
- Etichette brevi
- Poche linee incrociate
- Nomenclatura coerente
Preferisci più diagrammi piccoli
Invece di un enorme diagramma di sistema, usa diversi diagrammi focalizzati:
- Flusso delle richieste
- Topologia di deployment
- Modello di dati
- Ciclo di vita degli stati
- Percorso dei guasti
Questo è migliore per i lettori e migliore per gli schermi mobili.
Usa nomi stabili
Usa nomi che corrispondono al tuo codice, API o documentazione. Non chiamare la stessa cosa API, Backend e Server in diagrammi diversi a meno che non si tratti davvero di concetti diversi.
Etichetta le frecce importanti
Le frecce senza etichette vanno bene per diagrammi di flusso semplici. Nei diagrammi di sistema, le etichette spesso contano.
questo codice:
```mermaid
flowchart LR
Web -->|Richiesta HTTPS| API
API -->|Query SQL| DB
API -->|Pubblica evento| Queue
```
Produce questo diagramma:
Evita la sintassi troppo astuta
Mermaid può fare molte cose. Questo non significa che ogni articolo ne abbia bisogno. Favorisci la sintassi che un futuro mantentore può comprendere rapidamente.
Usa le virgolette per le etichette quando necessario
Se un’etichetta contiene caratteri che confondono Mermaid, racchiudila tra virgolette.
questo codice:
```mermaid
flowchart TD
A["L'utente clicca su /checkout"] --> B["POST /api/orders"]
```
Produce questo diagramma:
È un’abitudine piccola che previene fastidiosi fallimenti di rendering.
Pensa alla modalità scura
Molti siti Hugo supportano la modalità scura. Assicurati che il tuo tema Mermaid o il CSS del sito mantenga i diagrammi leggibili sia nell’aspetto chiaro che in quello scuro.
Errori comuni con Mermaid
Errore 1: Troppi dettagli
I cattivi diagrammi Mermaid spesso cercano di mostrare ogni caso limite. Questo li rende tecnicamente completi e praticamente illeggibili. La correzione è quasi sempre la stessa: dividi il diagramma in due o tre più piccoli, ciascuno che copre un aspetto, così i lettori possono seguire la logica senza dover tracciare una dozzina di frecce incrociate.
Errore 2: Etichette lunghe
Le etichette lunghe creano caselle ampie e layout brutti.
Invece di questo codice:
```mermaid
flowchart TD
A[L'utente invia il modulo di registrazione con il proprio indirizzo email e password]
```
Produce questo diagramma:
Preferisci questo codice:
```mermaid
flowchart TD
A[Invia modulo di registrazione]
```
Produce questo diagramma:
Spiega i dettagli nel paragrafo sotto il diagramma.
Errore 3: Direzione non chiara
Scegli una direzione e attieniti a essa. La maggior parte dei diagrammi di processo dovrebbe usare TD. La maggior parte dei diagrammi architetturali è più facile con LR.
Errore 4: Trattare Mermaid come strumento di design
Mermaid non è Figma. Non è pensato per diagrammi pixel-perfetti, e cercare di forzare questo ruolo porterà solo a frustrazione. Il suo punto di forza è la manutenibilità, non la perfezione visiva — e questo compromesso è intenzionale.
Consigli SEO per Mermaid nei blog tecnici
I diagrammi Mermaid possono rendere gli articoli tecnici più utili, ma i motori di ricerca hanno ancora bisogno di testo. Non affidarti solo ai diagrammi.
Per articoli Mermaid ottimizzati per SEO:
- Usa titoli H2 e H3 descrittivi.
- Spiega ogni diagramma nel testo vicino.
- Includi le parole chiave importanti nel testo normale.
- Mantieni gli esempi di codice copiabili.
- Aggiungi spiegazioni in stile “alt” sotto i diagrammi complessi.
- Usa un titolo e una descrizione nel front matter concisi.
- Evita di nascondere tutto il significato all’interno dell’SVG renderizzato.
Un diagramma Mermaid dovrebbe supportare l’articolo. Non dovrebbe essere l’unico luogo in cui esiste un’informazione importante.
Esempi Mermaid da copiare e incollare
Flusso di richiesta API
questo codice:
```mermaid
sequenceDiagram
participant Client
participant API
participant Auth
participant DB
Client->>API: GET /account
API->>Auth: Convalida token
Auth-->>API: Token valido
API->>DB: Carica account
DB-->>API: Dati account
API-->>Client: 200 OK
```
Produce questo diagramma:
Pipeline CI
questo codice:
```mermaid
flowchart TD
A[Push commit] --> B[Installa dipendenze]
B --> C[Esegui lint]
C --> D[Esegui test]
D --> E[Build sito]
E --> F[Deploy]
```
Produce questo diagramma:
Questo schema si mappa naturalmente a una configurazione CI reale. Per la sintassi passo-passo dei flussi di lavoro GitHub Actions, il Riferimento GitHub Actions è un utile compagno quando vuoi trasformare il diagramma sopra in una pipeline funzionante.
Flusso di pubblicazione
questo codice:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Editing
Editing --> Review
Review --> Published
Review --> Editing
Published --> [*]
```
Produce questo diagramma:
Modello di dati semplice
questo codice:
```mermaid
erDiagram
AUTHOR ||--o{ POST : writes
POST ||--o{ COMMENT : receives
AUTHOR {
string id
string name
}
POST {
string id
string title
datetime published_at
}
COMMENT {
string id
string body
}
```
Produce questo diagramma:
Quando non usare Mermaid
Non usare Mermaid quando:
- Il diagramma ha bisogno di un layout visivo preciso.
- Il design deve corrispondere esattamente a un sistema di brand.
- La visuale è prevalentemente decorativa.
- Il diagramma ha troppi nodi per essere letto.
- Uno screenshot spiegherebbe il concetto meglio.
- Il contenuto cambia raramente e ha bisogno di più cura che manutenibilità.
Mermaid è eccellente per la documentazione tecnica viva. È meno adatta per opere d’arte di livello presentazione. Per diagrammi di qualità documentale in contesti di stampa o PDF, LaTeX offre pacchetti come TikZ e pgfplots che ti danno un controllo di layout molto maggiore — il Riferimento LaTeX copre l’inclusione dei diagrammi insieme al resto degli strumenti LaTeX.
Pensieri finali
Mermaid è uno degli strumenti migliori per il blogging tecnico perché rispetta il modo in cui gli sviluppatori lavorano già: file di testo, Markdown, Git, code review e build ripetibili. Per tutto ciò che circonda i diagrammi — titoli, liste, tabelle, blocchi di codice — il Riferimento Markdown è il compagno di riferimento rapido da tenere accanto a questa guida.
I migliori diagrammi Mermaid non sono quelli più complessi. Sono i diagrammi che rendono un concetto ovvio e rimangono facili da modificare anche sei mesi dopo.
Usa Mermaid per i diagrammi che dovrebbero vivere insieme alla tua documentazione. Tienili piccoli, tienili leggibili e trattali come parte del codice sorgente del tuo articolo.
