Guida completa ai diagrammi Mermaid

Che cos'è Mermaid?

Perché usare Mermaid?

• 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:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[Alternative]
    C --> E[End]
    D --> E

sequenceDiagram
    participant User
    participant API
    participant DB
    User->>API: Request data
    API->>DB: Query
    DB-->>API: Results
    API-->>User: Response

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: Start
    Loading --> Success: Complete
    Loading --> Error: Fail
    Success --> [*]
    Error --> Idle: Retry

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    CUSTOMER {
        int id
        string name
        string email
    }

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Design :a1, 2024-01-01, 30d
    Development :a2, after a1, 45d

pie title Distribution
    "Category A" : 42
    "Category B" : 30
    "Category C" : 28

gitGraph
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop

Per iniziare con Mermaid

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

Risorse aggiuntive

• Documentazione ufficiale di Mermaid
• Repository GitHub di Mermaid
• Riferimento sintassi Mermaid