La creazione di diagrammi è sempre stata una delle parti che meno mi piacciono della documentazione. Sprecare ore a spostare caselle e finire comunque con qualcosa che sembrava amatoriale. Questo è cambiato quando ho scoperto Mermaid. In questo post, condividerò come uso Mermaid CLI per creare diagrammi usando solo testo, e come gli strumenti di intelligenza artificiale hanno completamente trasformato e snellito questo processo.

Cos'è Mermaid?

Mermaid è uno strumento gratuito e open source che trasforma il testo in diagrammi, un po' come Markdown trasforma il testo in contenuti formattati. È completamente gratuito sotto licenza MIT, quindi puoi usarlo per lavoro o per scopi personali senza preoccuparti dei costi di licenza. Può essere usato per creare tutti i tipi di diagrammi, come:

Diagrammi di flusso
Diagrammi di sequenza
Diagrammi di classe
Diagrammi entità-relazione
Diagrammi di Gantt
Diagrammi a torta
Mappe del percorso utente
Grafici Git
Diagrammi di stato
E molti altri

Ciò che amo di più è che non devo più trascinare caselle. Scrivo solo testo e Mermaid crea il diagramma. Dopo anni di lotta con gli strumenti di diagrammazione tradizionali, questo approccio sembra una rivelazione.

Iniziare con Mermaid CLI

Ho iniziato a usare Mermaid nel browser, ma la versione CLI (Command Line Interface) è dove avviene la vera magia. Ti permette di trasformare i tuoi diagrammi testuali in file immagine effettivi che puoi inserire in documenti, presentazioni o ovunque. Ed è super facile da usare.

La sintassi di base per usare Mermaid CLI è:

npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png

Questo comando:

npx @mermaid-js/mermaid-cli: Esegue lo strumento Mermaid CLI senza richiedere un'installazione globale
-i diagram.mmd: Specifica il file di input contenente la definizione del tuo diagramma Mermaid
-o diagram.png: Imposta il nome del file di output e il formato (PNG in questo caso)

Puoi anche generare file SVG che sono scalabili e perfetti per l'uso sul web:

npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

Puoi anche visualizzare rapidamente il tuo codice Mermaid online usando strumenti come MermaidChart, che è ottimo per testare e condividere diagrammi senza installare nulla.

Creare il Tuo Primo Diagramma Mermaid

Iniziamo con un semplice diagramma di flusso. Crea un file chiamato flowchart.mmd con questo contenuto:

flowchart TD
A[Inizio] --> B{Decisione}
B -->|Sì| C[Processo 1]
B -->|No| D[Processo 2]
C --> E[Fine]
D --> E

Ora, genera un'immagine PNG di questo diagramma:

npx @mermaid-js/mermaid-cli -i flowchart.mmd -o flowchart.png

Questo creerà un diagramma di flusso pulito e dall'aspetto professionale che mostra un semplice processo decisionale, come questo:

Diagramma di flusso semplice che mostra un processo decisionale

Puoi usare questo stesso approccio per qualsiasi tipo di diagramma supportato da Mermaid.

Ad esempio, se hai bisogno di visualizzare un'architettura di sistema (come ho fatto di recente), potresti creare qualcosa di simile:

flowchart TD
Client([Browser Web]) --HTTP/HTTPS--> LB[Load Balancer]
LB --> API1[Server API 1]
LB --> API2[Server API 2]
API1 --> DB[(Database)]
API2 --> DB
API1 --> Cache[(Cache Redis)]
API2 --> Cache

Che produce questo diagramma:

Diagramma di architettura che mostra server web, load balancer e database

Come l'IA Potenzia la Creazione di Diagrammi

È qui che l'intelligenza artificiale diventa un punto di svolta. Invece di scrivere manualmente diagrammi Mermaid, strumenti AI come Cursor e Windsurf possono analizzare descrizioni testuali e generare automaticamente definizioni di diagrammi per te.

Recentemente ho dovuto creare un diagramma di architettura per un progetto AWS + Drupal con un'architettura complessa. Senza AI, ci sarebbe voluto molto tempo per mappare tutti i componenti e le connessioni. Invece, ho fornito le specifiche del progetto all'assistente AI di Cursor, gli ho chiesto di estrarre i componenti del sistema e le loro relazioni, e ho ottenuto codice Mermaid che mi ha aiutato a creare il diagramma in modo più efficiente.

Utilizzare l'IA di Cursor per Generare Diagrammi

Cursor è un IDE con una potente IA che comprende sia il codice che il linguaggio naturale. La sua capacità di interpretare descrizioni tecniche e convertirle in sintassi Mermaid strutturata è notevole. Ecco il mio flusso di lavoro tipico:

Copia il testo pertinente che descrive il concetto che vuoi visualizzare
Usa un prompt come: "Genera un diagramma Mermaid basato su questa descrizione"
Cursor analizzerà il testo e genererà la sintassi Mermaid appropriata
Salva il codice Mermaid generato in un file .mmd
Usa Mermaid CLI per convertirlo in un'immagine

Ad esempio, potresti dare a Cursor istruzioni come:

"Crea un diagramma di flusso Mermaid che mostri un processo di registrazione utente"
"Genera un diagramma di sequenza Mermaid per questo flusso di richieste API"
"Converti questa timeline di progetto in un diagramma di Gantt Mermaid"
"Crea un diagramma di classe Mermaid da questa descrizione del modello di dominio"

In pochi secondi, avrai un diagramma Mermaid completo che rappresenta accuratamente il tuo concetto.

Andare Oltre con l'IA di Windsurf

Windsurf (da Codeium) sfrutta l'IA per portare l'automazione dei diagrammi ancora più avanti. I suoi modelli AI possono analizzare intere codebase o set di documentazione per creare script che:

Scansionano file di testo alla ricerca di descrizioni che potrebbero essere visualizzate
Estraggono elementi chiave e relazioni
Generano la sintassi Mermaid appropriata in base al tipo di contenuto
Eseguono automaticamente Mermaid CLI per creare immagini di diagrammi
Includono questi diagrammi nei tuoi documenti

Ciò crea un flusso di lavoro di documentazione continuo in cui i tuoi diagrammi rimangono sincronizzati con i tuoi contenuti scritti. L'IA può rilevare quando il tuo codice o la tua documentazione cambiano abbastanza da giustificare aggiornamenti dei diagrammi, rendendo l'intero processo quasi automatico.

Tipi di Diagrammi Avanzati

Mermaid supporta molti tipi di diagrammi oltre ai semplici diagrammi di flusso. Ecco alcuni utili per la documentazione dell'architettura:

Diagrammi di Sequenza

Perfetti per illustrare come i componenti interagiscono nel tempo:

sequenceDiagram
participant Utente
participant API
participant Database

Utente->>API: GET /prodotti
API->>Database: Interroga prodotti
Database-->>API: Restituisci risultati
API-->>Utente: Risposta JSON

Che produce questo diagramma di sequenza:

Diagramma di sequenza che mostra il flusso di richieste API tra Utente, API e Database

Diagrammi di Classe

Ideali per mostrare la progettazione orientata agli oggetti:

classDiagram
class Ordine {
    +String id
    +Date createdAt
    +OrderStatus status
    +calcolaTotale()
}
class Cliente {
    +String id
    +String nome
    +String email
    +effettuaOrdine()
}
Cliente "1" -- "molti" Ordine: effettua

Che produce questo diagramma di classe:

Diagramma di classe che mostra le classi Cliente e Ordine con la loro relazione

Diagrammi Entità Relazione

Ottimi per la progettazione di database:

erDiagram
CLIENTE ||--o{ ORDINE : effettua
ORDINE ||--|{ ELEMENTO_ORDINE : contiene
CLIENTE }|..|{ INDIRIZZO_CONSEGNA : usa

Che produce questo diagramma entità relazione:

Diagramma Entità Relazione che mostra le relazioni tra cliente, ordine, elemento d'ordine e indirizzo di consegna

Esempi Pratici

Mermaid CLI può essere utilizzata per varie esigenze di visualizzazione, inclusa la documentazione dell'architettura di sistema (come menzionato in precedenza), ma anche per:

Pianificazione del Progetto

Per la pianificazione del progetto, puoi creare un diagramma di Gantt che mostri fasi e dipendenze:

gantt
title Timeline Progetto
formatoData  YYYY-MM-DD
section Ricerca
Raccolta requisiti :a1, 2025-01-01, 10g
Ricerca di mercato       :dopo a1, 7g
section Sviluppo
Sviluppo Frontend  :b1, 2025-01-18, 14g
Sviluppo Backend   :b2, 2025-01-18, 21g
section Test
Test di integrazione   :c1, dopo b1 b2, 7g
Accettazione utente       :c2, dopo c1, 7g

Che produce questa visualizzazione della timeline:

Diagramma di Gantt che mostra la timeline del progetto con le fasi di sviluppo

Documentazione dei Processi

Per documentare i processi aziendali, Mermaid può creare diagrammi di flusso chiari:

flowchart TD
Inizio([Ordine Cliente]) --> A{Scorte disponibili?}
A -->|Sì| B[Elabora pagamento]
A -->|No| C[Processo di ordine arretrato]
B --> D[Spedisci prodotto]
C --> E[Notifica cliente]
D & E --> Fine([Ordine completato])

Che produce questo diagramma di flusso del processo:

Diagramma di flusso del processo che mostra un flusso di lavoro di ordini cliente

Possibilità Future con IA e Automazione

La combinazione di Mermaid CLI e strumenti AI apre entusiasmanti possibilità per l'automazione della documentazione. Immagino un sistema che potrebbe:

Monitorare i file di documentazione per le modifiche
Utilizzare l'IA per identificare contenuti che potrebbero beneficiare della visualizzazione
Generare la sintassi Mermaid appropriata in base al contenuto
Eseguire automaticamente Mermaid CLI per creare nuove immagini di diagrammi
Incorporare in modo intelligente i diagrammi nella documentazione con il contesto appropriato

Un tale sistema manterrebbe i diagrammi sincronizzati con la documentazione senza intervento manuale. Sebbene non abbia ancora costruito questo sistema, gli attuali strumenti AI e Mermaid CLI lo rendono del tutto possibile.

Suggerimenti per Diagrammi Migliori

Usa forme significative: Mermaid offre varie forme di nodi per distinguere diversi tipi di componenti (database, servizi, sistemi esterni)
Aggiungi colore per chiarezza: Usa i colori per raggruppare componenti correlati o evidenziare elementi importanti
Mantieni la semplicità: Evita di sovraffollare i diagrammi; crea più diagrammi focalizzati invece di uno complesso
Usa sottografi: Raggruppa componenti correlati usando sottografi per mostrare confini logici
Aggiungi titoli e descrizioni: Rendi i tuoi diagrammi autoesplicativi con titoli chiari e brevi descrizioni

In Sintesi

Mermaid offre un approccio pratico alla creazione di diagrammi che si integra bene con i flussi di lavoro di sviluppo. La natura basata su testo dei diagrammi Mermaid li rende adatti al controllo di versione e più facili da mantenere rispetto ai formati di diagrammi tradizionali.

Se combinato con strumenti AI, il processo diventa ancora più efficiente. Questi strumenti possono aiutare a generare codice per diagrammi da descrizioni, rendendolo accessibile anche a coloro che non hanno una profonda conoscenza tecnica.

Ecco alcuni pensieri finali sull'uso di Mermaid:

Curva di apprendimento: La sintassi è relativamente semplice da imparare, specialmente se hai già familiarità con markdown o altri formati basati su testo.
Integrazione: I diagrammi Mermaid funzionano in molte piattaforme tra cui GitHub, Notion e altri sistemi di documentazione.
Costo: Essendo uno strumento open-source con licenza MIT, Mermaid è gratuito da usare per qualsiasi scopo.
Efficienza: La creazione di diagrammi basata su testo può essere più veloce della diagrammazione tradizionale una volta che si ha familiarità con la sintassi.
Facilità di configurazione: L'uso di npx per eseguire Mermaid CLI elimina i problemi di installazione.

Se stai cercando di migliorare il tuo processo di documentazione, considera di provare Mermaid per il tuo prossimo progetto. La capacità di creare diagrammi professionali direttamente da descrizioni testuali, con la potenziale assistenza di strumenti AI, potrebbe trasformare il modo in cui affronti la visualizzazione nel tuo lavoro.

Automation

Automatizzare la Creazione di Diagrammi con Mermaid CLI e Strumenti AI