 |
Nel mondo dello sviluppo software e della documentazione tecnica, i diagrammi sono uno strumento fondamentale per spiegare concetti complessi, architetture, flussi di processo e relazioni tra componenti. Tuttavia, creare e mantenere diagrammi aggiornati può diventare rapidamente oneroso, soprattutto quando si usano strumenti grafici tradizionali.
È qui che entra in gioco Mermaid: un linguaggio di descrizione testuale che consente di creare diagrammi in modo strutturato, versionabile e facilmente mantenibile.
Cos’è Mermaid
Mermaid è una libreria open source che permette di generare diagrammi e grafici a partire da una semplice sintassi testuale. Invece di disegnare manualmente forme e frecce, si descrive il diagramma tramite codice, che viene poi renderizzato automaticamente.
Questo approccio “diagram-as-code” si sposa perfettamente con le pratiche moderne di sviluppo e documentazione.
Il confronto con i tool drag & drop
La maggior parte degli strumenti tradizionali per creare diagrammi — come Microsoft Visio, Lucidchart o draw.io — si basa su un approccio visuale: si trascinano elementi sulla tela e si collegano tra loro.
Questo modello è:
- intuitivo
- immediato
- accessibile anche ai non tecnici
Con Mermaid, invece, il paradigma cambia completamente: non si disegna, si scrive.
Ed è qui che entra in gioco un aspetto importante:
👉 per usare Mermaid in modo efficace è necessario studiarne la sintassi.
La curva di apprendimento: un investimento iniziale
Mermaid non è complesso, ma non è nemmeno “zero effort”. Per creare diagrammi ben strutturati occorre:
- comprendere le diverse tipologie di diagrammi
- imparare le parole chiave (flowchart, sequenceDiagram, classDiagram, ecc.)
- capire come definire nodi, relazioni, condizioni
- conoscere alcune convenzioni sintattiche
Chi è abituato ai tool drag & drop può percepire inizialmente Mermaid come meno immediato. Non c’è una tela grafica su cui “provare e vedere”: c’è del testo da scrivere correttamente.
Tuttavia, questa apparente barriera iniziale porta con sé un vantaggio importante:
obbliga a formalizzare il pensiero.
Scrivere un diagramma significa strutturarlo logicamente prima ancora di vederlo renderizzato.
Davvero non c'è il drag&drop?
Continua a leggere per avere il quadro completo sul mondo Mermaid 😉
Perché vale la pena impararlo
L’investimento iniziale nella sintassi viene ripagato nel tempo grazie a:
1. Versionamento naturale
Essendo testo puro, i diagrammi Mermaid possono essere:
- salvati in repository Git
- revisionati tramite pull request
- confrontati con diff chiari e comprensibili
Niente più file binari impossibili da confrontare.
2. Manutenzione semplificata
Aggiornare un diagramma significa modificare poche righe di testo. Questo riduce il rischio di diagrammi obsoleti e incoraggia a mantenerli allineati al codice reale.
3. Coerenza strutturale
La sintassi impone una certa disciplina. Questo porta a diagrammi più coerenti, meno “creativi” ma più leggibili e standardizzati.
4. Integrazione nei workflow moderni
Mermaid è supportato in molti ambienti Markdown e tool di documentazione, rendendolo perfettamente integrabile nei flussi DevOps e nelle pipeline di documentazione.
Un esempio semplice
Ecco un esempio di diagramma di flusso scritto in Mermaid:
flowchart TD
A[User] --> B[Send request]
B --> C{Authenticated?}
C -->|Yes| D[Process the request]
C -->|No| E[Show error]Con poche righe di testo si ottiene un diagramma chiaro, leggibile e facilmente modificabile.
Come provare subito l'esempio
Se vuoi sperimentare immediatamente l’esempio visto sopra, puoi utilizzare mermaid.live, un editor online gratuito che permette di scrivere codice Mermaid e visualizzare in tempo reale il diagramma generato.
È sufficiente accedere al sito:
https://mermaid.live/
L’interfaccia è molto semplice: nella parte sinistra puoi scrivere o incollare il codice del diagramma, mentre nella parte destra viene mostrato il rendering automatico. Questo ti consente di fare modifiche rapide, comprendere meglio la sintassi e prendere confidenza con il funzionamento di Mermaid senza dover installare nulla.
 |
| mermaid.live |
È il modo più veloce per iniziare a sperimentare e comprendere concretamente l’approccio “diagram-as-code”.
Ma c'è di meglio...Playground
- cambiare le forme degli elementi nel diagramma
- cambiare lo stile grafico del diagramma
- definirne l'orientamento
- cambiare tipo di visualizzazione - gerarchica vs adattiva
 |
| Playground editor |
Quando scegliere Mermaid (e quando no)
Mermaid è ideale quando:
- i diagrammi fanno parte della documentazione tecnica
- è importante mantenerli sotto versionamento
- il team è abituato a lavorare con codice
- si vuole favorire coerenza e standardizzazione
Potrebbe invece non essere la scelta migliore quando:
- serve massima libertà grafica
- il pubblico è prevalentemente non tecnico
- il diagramma è più orientato al design visivo che alla struttura logica
Davvero Mermaid non ha il drag&drop?!
Il panorama degli strumenti collegati a Mermaid è in continua evoluzione, e in particolare esiste uno strumento che va proprio nella direzione del drag&drop: Whiteboard.
Mermaid Whiteboard è un ambiente collaborativo dove puoi lavorare sui diagrammi in due modalità:
- Modalità testuale – scrivi la sintassi come nei normali editor “diagram-as-code” (visti prima).
- Modalità visuale drag & drop – puoi spostare, ridimensionare e connettere elementi direttamente con un’interfaccia grafica, più simile a un editor tradizionale.
Questa dualità è pensata per adattarsi a team con profili diversi: chi ama il controllo tramite codice e chi preferisce lavorare con elementi visivi.
Ma cosa succede al codice Mermaid se modifichi il diagramma visualmente?
In Mermaid Whiteboard, quando modifichi un diagramma nella modalità visuale, lo strumento può rigenerare o aggiornare la rappresentazione testuale (codice Mermaid) per riflettere le modifiche apportate — questo è proprio uno dei punti forti dell’approccio “dual mode” offerto dal Whiteboard, dove il codice e la visualizzazione convivono e si sincronizzano.
In altri strumenti o plugin simili, invece, il codice testuale rimane la fonte primaria di verità: potresti vedere una rappresentazione visuale, ma qualsiasi modifica avanzata richiede di aggiornare manualmente il testo Mermaid oppure utilizzare editor specifici che mantengono uno stato sincronizzato tra testo e visuale — non è garantito in tutti i casi che avvenga automaticamente senza confusione.
Conclusione
Mermaid rappresenta un cambio di paradigma: dai diagrammi “disegnati” ai diagrammi scritti.
Sì, richiede di imparare una sintassi.
Sì, non è immediato come trascinare forme su una tela.
Ma in cambio offre:
- struttura
- versionabilità
- coerenza
- integrazione nei flussi di sviluppo moderni
- una serie di strumenti (come Whiteboard) per superare i suoi limiti (come l'assenza iniziale del drag&drop)
Per team tecnici e documentazione evoluta, è spesso un investimento che ripaga nel medio-lungo periodo.
Ma non finisce qui
- Pagina GitHub di Mermaid dove puoi trovare tutte le info e i dettagli → https://github.com/mermaid-js/mermaid?tab=readme-ov-file
- Integrare Mermaid con altre piattaforme (es. JIRA) → https://mermaid.js.org/ecosystem/integrations-community.html
Follow me #techelopment
Official site: www.techelopment.it
facebook: Techelopment
instagram: @techelopment
X: techelopment
Bluesky: @techelopment
telegram: @techelopment_channel
whatsapp: Techelopment
youtube: @techelopment
