Guida completa ai diagrammi Mermaid.js
Impara a creare diagrammi professionali con una sintassi semplice basata sul testo
Che cos'è Mermaid.js?
Mermaid è uno strumento di diagrammazione e charting basato su JavaScript che usa definizioni testuali ispirate a Markdown per creare e modificare diagrammi dinamicamente. È un progetto open source che consente di generare diagrammi da semplici descrizioni testuali.
Invece di usare strumenti di disegno complessi, scrivi una sintassi simile al codice che descrive il tuo diagramma e Mermaid lo rende come diagramma visivo. Questo approccio rende i diagrammi versionabili, facili da aggiornare e perfetti per la documentazione.
Mermaid si integra perfettamente con piattaforme di documentazione, wiki e file Markdown, rendendolo uno strumento preferito da sviluppatori e technical writer.
Perché usare Mermaid.js?
- Controllo versione: i diagrammi sono file di testo, quindi possono essere tracciati in Git insieme al tuo codice
- Aggiornamenti rapidi: cambia poche righe di testo invece di ridisegnare interi diagrammi
- Coerenza: Mermaid gestisce automaticamente layout e stile, garantendo diagrammi coerenti
- Nessun tool di design: non serve Visio, Lucidchart o altri strumenti costosi
- Documentazione come codice: mantieni i diagrammi nello stesso repository della documentazione
- Multipiattaforma: funziona nei browser e in Node.js e si integra con molte piattaforme
- Gratuito e open source: nessun costo di licenza, community attiva
- Molteplici tipi di diagrammi: supporta flowchart, diagrammi di sequenza, diagrammi di classi e altro
Tipi di diagrammi supportati
Mermaid supporta un'ampia varietà di tipi di diagrammi per diverse esigenze di documentazione:
Diagramma di flusso
Visualizza flussi di lavoro, processi e alberi decisionali con nodi e archi.
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Process]
B -->|No| D[Alternative]
C --> E[End]
D --> ECaso d'uso: Flussi di processo, algoritmi, logica decisionale
Diagramma di sequenza
Mostra interazioni tra attori o sistemi diversi nel tempo.
sequenceDiagram
participant User
participant API
participant DB
User->>API: Request data
API->>DB: Query
DB-->>API: Results
API-->>User: ResponseCaso d'uso: Interazioni API, comunicazione tra sistemi, flussi utente
Diagramma di classi
Modella sistemi orientati agli oggetti con classi, attributi e relazioni.
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+bark()
}
Animal <|-- DogCaso d'uso: Architettura software, design OOP, schemi di database
Diagramma di stato
Rappresenta stati e transizioni in un sistema o processo.
stateDiagram-v2
[*] --> Idle
Idle --> Loading: Start
Loading --> Success: Complete
Loading --> Error: Fail
Success --> [*]
Error --> Idle: RetryCaso d'uso: Macchine a stati, gestione del ciclo di vita, stati UI
Diagramma ER
Modella strutture di database e relazioni tra entità.
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
CUSTOMER {
int id
string name
string email
}Caso d'uso: Progettazione database, modellazione dati, architettura di sistema
Diagramma di Gantt
Pianifica e visualizza pianificazioni e timeline di progetto.
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Design :a1, 2024-01-01, 30d
Development :a2, after a1, 45dCaso d'uso: Pianificazione progetti, timeline di sprint, roadmap
Grafico a torta
Mostra dati proporzionali e percentuali in modo visivo.
pie title Distribution
"Category A" : 42
"Category B" : 30
"Category C" : 28Caso d'uso: Risultati di sondaggi, quota di mercato, allocazione risorse
Grafico Git
Visualizza strategie di branching Git e cronologia dei commit.
gitGraph
commit
branch develop
checkout develop
commit
checkout main
merge developCaso d'uso: Documentazione del workflow Git, strategie di branching
Per iniziare con Mermaid
1. Scegli il tipo di diagramma
Inizia decidendo quale tipo di diagramma rappresenta meglio ciò che vuoi mostrare. Ogni tipo di diagramma inizia con una parola chiave specifica come 'flowchart', 'sequenceDiagram' o 'classDiagram'.
2. Scrivi la sintassi testuale
Usa la sintassi semplice di Mermaid per descrivere il tuo diagramma. La sintassi è intuitiva e si legge quasi come un linguaggio naturale. Ad esempio, 'A --> B' crea una freccia da A a B.
3. Anteprima del diagramma
Usa il nostro visualizzatore online o qualsiasi strumento compatibile con Mermaid per vedere il diagramma renderizzato in tempo reale. Apporta le modifiche necessarie finché non sei soddisfatto.
4. Esporta e condividi
Esporta il diagramma in SVG o PNG per le presentazioni, oppure condividi un URL con il tuo team. Puoi anche incorporare Mermaid direttamente nei file Markdown.
Best practice
- Mantieni i diagrammi concentrati su un singolo concetto o workflow
- Usa etichette significative che descrivano la logica di business reale
- Suddividi i diagrammi complessi in diagrammi più piccoli e interconnessi
- Aggiungi commenti usando %% per spiegare sezioni complesse
- Usa convenzioni di denominazione coerenti in tutti i diagrammi
- Testa i diagrammi nell'ambiente target prima di finalizzarli
- Includi indicazioni di direzione (TD, LR) per controllare il layout quando necessario
- Usa i subgraph per raggruppare nodi correlati nei diagrammi di flusso
- Usa le opzioni di stile con moderazione per mantenere la leggibilità
- Versiona i file sorgente dei diagrammi insieme al tuo codice
Casi d'uso comuni
Documentazione software
Documenta architettura di sistema, flussi API e interazioni tra componenti insieme al tuo codice.
Pianificazione di progetto
Crea diagrammi di Gantt per pianificazione sprint, timeline di progetto e allocazione delle risorse.
Proposte tecniche
Visualizza soluzioni proposte, design di sistema e decisioni architetturali.
User journey
Mappa flussi utente, esperienze cliente e pattern di interazione.
Progettazione database
Modella relazioni tra entità, strutture di schema e dipendenze dei dati.
Documentazione dei processi
Documenta processi aziendali, workflow e procedure operative standard.
Materiali educativi
Crea diagrammi chiari e versionati per tutorial e corsi tecnici.
Documentazione API
Illustra flussi di richiesta/risposta, sequenze di autenticazione e interazioni degli endpoint.
Risorse aggiuntive
Domande frequenti
Domande comuni sull'uso di Mermaid Viewer e sulla creazione di diagrammi
Pronto a creare il tuo primo diagramma?
Prova il nostro visualizzatore Mermaid online gratuito e inizia a creare diagrammi professionali in pochi minuti.
Apri il visualizzatore Mermaid