Diagrammi

Markdown supporta la creazione di vari tipi di diagrammi e flowchart tramite la sintassi Mermaid, offrendo espressione visiva alla tua documentazione.

Introduzione a Mermaid

Mermaid è uno strumento di generazione diagrammi basato su testo che supporta diversi tipi di diagrammi:

Flowchart
Diagramma di sequenza
Gantt Chart
Diagramma delle classi
Diagramma degli stati
Grafico a torta
User Journey
Git Graph

Sintassi di base

Flowchart

markdown

```mermaid
flowchart TD
    A[Start] --> B{Logged in?}
    B -->|Yes| C[Show Home]
    B -->|No| D[Show Login]
    C --> E[End]
    D --> F[User Login]
    F --> G{Login Success?}
    G -->|Yes| C
    G -->|No| H[Show Error]
    H --> D


**Risultato renderizzato:**

```mermaid
flowchart TD
    A[Start] --> B{Logged in?}
    B -->|Yes| C[Show Home]
    B -->|No| D[Show Login]
    C --> E[End]
    D --> F[User Login]
    F --> G{Login Success?}
    G -->|Yes| C
    G -->|No| H[Show Error]
    H --> D

Diagramma di sequenza

markdown

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant Database
    
    User->>Frontend: Login Request
    Frontend->>Backend: Validate User
    Backend->>Database: Query User Data
    Database-->>Backend: Return User Info
    Backend-->>Frontend: Validation Result
    Frontend-->>User: Login Response


**Risultato renderizzato:**

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant Database
    
    User->>Frontend: Login Request
    Frontend->>Backend: Validate User
    Backend->>Database: Query User Data
    Database-->>Backend: Return User Info
    Backend-->>Frontend: Validation Result
    Frontend-->>User: Login Response

Dettagli Flowchart

Tipi di nodo

markdown

```mermaid
flowchart LR
    A[Rectangle Node]
    B(Rounded Node)
    C((Circle Node))
    D{Diamond Node}
    E[[Subroutine]]
    F[(Database)]
    G>Label Node]


**Risultato renderizzato:**

```mermaid
flowchart LR
    A[Rectangle Node]
    B(Rounded Node)
    C((Circle Node))
    D{Diamond Node}
    E[[Subroutine]]
    F[(Database)]
    G>Label Node]

Tipi di collegamento

markdown

```mermaid
flowchart TD
    A --> B
    C --- D
    E -.-> F
    G ==> H
    I --o J
    K --x L


**Risultato renderizzato:**

```mermaid
flowchart TD
    A --> B
    C --- D
    E -.-> F
    G ==> H
    I --o J
    K --x L

Controllo direzione

markdown

<!-- Dall'alto verso il basso -->
```mermaid
flowchart TD
    A --> B

mermaid

flowchart BT
    A --> B

mermaid

flowchart LR
    A --> B

mermaid

flowchart RL
    A --> B


### Esempio di flowchart complesso

```markdown
```mermaid
flowchart TD
    Start([Project Start]) --> Analysis[Requirement Analysis]
    Analysis --> Design[System Design]
    Design --> Dev{Development Stage}
    
    Dev --> Frontend[Frontend Dev]
    Dev --> Backend[Backend Dev]
    Dev --> Database[Database Design]
    
    Frontend --> FrontTest[Frontend Test]
    Backend --> BackTest[Backend Test]
    Database --> DataTest[Data Test]
    
    FrontTest --> Integration[Integration Test]
    BackTest --> Integration
    DataTest --> Integration
    
    Integration --> Deploy{Deployment Prep}
    Deploy -->|Pass| Production[Production]
    Deploy -->|Fail| Bug[Fix Issues]
    Bug --> Integration
    
    Production --> Monitor[Monitoring]
    Monitor --> End([Project Complete])
    
    style Start fill:#e1f5fe
    style End fill:#e8f5e8
    style Bug fill:#ffebee


**Risultato renderizzato:**

```mermaid
flowchart TD
    Start([Project Start]) --> Analysis[Requirement Analysis]
    Analysis --> Design[System Design]
    Design --> Dev{Development Stage}
    
    Dev --> Frontend[Frontend Dev]
    Dev --> Backend[Backend Dev]
    Dev --> Database[Database Design]
    
    Frontend --> FrontTest[Frontend Test]
    Backend --> BackTest[Backend Test]
    Database --> DataTest[Data Test]
    
    FrontTest --> Integration[Integration Test]
    BackTest --> Integration
    DataTest --> Integration
    
    Integration --> Deploy{Deployment Prep}
    Deploy -->|Pass| Production[Production]
    Deploy -->|Fail| Bug[Fix Issues]
    Bug --> Integration
    
    Production --> Monitor[Monitoring]
    Monitor --> End([Project Complete])
    
    style Start fill:#e1f5fe
    style End fill:#e8f5e8
    style Bug fill:#ffebee

Dettagli diagramma di sequenza

Sintassi di base

mermaid

sequenceDiagram
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I'm good, thanks!
    Alice-)Bob: Goodbye!

Risultato renderizzato:

mermaid

sequenceDiagram
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I'm good, thanks!
    Alice-)Bob: Goodbye!

Barre di attivazione e lifeline

mermaid

sequenceDiagram
    participant A as Client
    participant B as Server
    
    A->>+B: Request Data
    Note right of B: Processing Request
    B-->>-A: Return Data
    
    A->>+B: Another Request
    B->>+B: Internal Processing
    B-->>-B: Processing Done
    B-->>-A: Return Result

Risultato renderizzato:

mermaid

sequenceDiagram
    participant A as Client
    participant B as Server
    
    A->>+B: Request Data
    Note right of B: Processing Request
    B-->>-A: Return Data
    
    A->>+B: Another Request
    B->>+B: Internal Processing
    B-->>-B: Processing Done
    B-->>-A: Return Result

Cicli e condizioni

mermaid

sequenceDiagram
    participant U as User
    participant S as System
    
    U->>S: Login Request
    
    alt Username Exists
        S->>S: Validate Password
        alt Password Correct
            S-->>U: Login Success
        else Password Incorrect
            S-->>U: Wrong Password
        end
    else Username Not Found
        S-->>U: User Not Found
    end
    
    opt Remember Me
        S->>S: Save Login State
    end

Risultato renderizzato:

mermaid

sequenceDiagram
    participant U as User
    participant S as System
    
    U->>S: Login Request
    
    alt Username Exists
        S->>S: Validate Password
        alt Password Correct
            S-->>U: Login Success
        else Password Incorrect
            S-->>U: Wrong Password
        end
    else Username Not Found
        S-->>U: User Not Found
    end
    
    opt Remember Me
        S->>S: Save Login State
    end

Diagramma delle classi

mermaid

classDiagram
    class Animal {
        +String name
        +int age
        +eat()
        +sleep()
    }
    
    class Dog {
        +String breed
        +bark()
        +wagTail()
    }
    
    class Cat {
        +String color
        +meow()
        +purr()
    }
    
    Animal <|-- Dog
    Animal <|-- Cat
    
    class Owner {
        +String name
        +feedPet()
    }
    
    Owner --> Animal : owns

Risultato renderizzato:

mermaid

classDiagram
    class Animal {
        +String name
        +int age
        +eat()
        +sleep()
    }
    
    class Dog {
        +String breed
        +bark()
        +wagTail()
    }
    
    class Cat {
        +String color
        +meow()
        +purr()
    }
    
    Animal <|-- Dog
    Animal <|-- Cat
    
    class Owner {
        +String name
        +feedPet()
    }
    
    Owner --> Animal : owns

Diagramma degli stati

mermaid

stateDiagram-v2
    [*] --> Idle
    Idle --> Running : Start
    Running --> Paused : Pause
    Running --> Finished : End
    Paused --> Running : Resume
    Paused --> Stopped : Stop
    Stopped --> Idle : Reset
    Finished --> Idle : Reset
    Finished --> [*]
    
    state Running {
        [*] --> Init
        Init --> Processing
        Processing --> Validate
        Validate --> [*]
    }

Risultato renderizzato:

mermaid

stateDiagram-v2
    [*] --> Idle
    Idle --> Running : Start
    Running --> Paused : Pause
    Running --> Finished : End
    Paused --> Running : Resume
    Paused --> Stopped : Stop
    Stopped --> Idle : Reset
    Finished --> Idle : Reset
    Finished --> [*]
    
    state Running {
        [*] --> Init
        Init --> Processing
        Processing --> Validate
        Validate --> [*]
    }

Gantt Chart

mermaid

gantt
    title Project Development Timeline
    dateFormat  YYYY-MM-DD
    section Requirement Analysis
    Requirement Collection          :done,    des1, 2024-01-01,2024-01-05
    Requirement Analysis            :done,    des2, after des1, 5d
    Requirement Review              :done,    des3, after des2, 2d
    
    section Design Phase
    System Design                   :active,  design1, 2024-01-12, 7d
    UI Design                       :         design2, after design1, 5d
    Database Design                 :         design3, after design1, 3d
    
    section Development Phase
    Frontend Development            :         dev1, after design2, 10d
    Backend Development             :         dev2, after design3, 12d
    Testing                         :         test1, after dev1, 5d

Grafico a torta

mermaid

pie title Website Traffic Sources
    "Search Engine" : 45
    "Social Media" : 25
    "Direct" : 20
    "Email Marketing" : 7
    "Other" : 3

User Journey

mermaid

journey
    title User Shopping Journey
    section Discovery
      Visit Homepage: 3: User
      Browse Products: 4: User
      Search Products: 4: User
    section Consideration
      View Details: 4: User
      Compare Prices: 3: User
      Read Reviews: 5: User
    section Purchase
      Add to Cart: 4: User
      Checkout: 3: User
      Pay: 2: User
    section Use
      Receive Product: 5: User
      Use Product: 4: User
      Write Review: 4: User

Git Graph

mermaid

gitgraph
    commit id: "Initial Commit"
    commit id: "Add User Module"
    branch feature/auth
    commit id: "Add Login Feature"
    commit id: "Add Register Feature"
    checkout main
    commit id: "Fix Home Bug"
    merge feature/auth
    commit id: "v1.0 Release"
    branch hotfix
    commit id: "Urgent Fix"
    checkout main
    merge hotfix
    commit id: "v1.0.1 Release"

Scenari reali

Schema architettura di sistema

mermaid

flowchart TB
    subgraph "User Layer"
        Web[Web Browser]
        Mobile[Mobile App]
        API[API Client]
    end
    
    subgraph "Gateway Layer"
        Gateway[API Gateway]
        Auth[Auth Service]
    end
    
    subgraph "Service Layer"
        UserService[User Service]
        OrderService[Order Service]
        PaymentService[Payment Service]
        NotificationService[Notification Service]
    end
    
    subgraph "Data Layer"
        UserDB[(User DB)]
        OrderDB[(Order DB)]
        Cache[(Redis Cache)]
        Queue[Message Queue]
    end
    
    Web --> Gateway
    Mobile --> Gateway
    API --> Gateway
    
    Gateway --> Auth
    Gateway --> UserService
    Gateway --> OrderService
    Gateway --> PaymentService
    
    UserService --> UserDB
    OrderService --> OrderDB
    PaymentService --> Queue
    NotificationService --> Queue
    
    UserService --> Cache
    OrderService --> Cache
    
    style Gateway fill:#e1f5fe
    style Auth fill:#fff3e0
    style Cache fill:#f3e5f5

Flusso chiamata API

mermaid

sequenceDiagram
    participant C as Client
    participant G as API Gateway
    participant A as Auth Service
    participant U as User Service
    participant D as Database
    participant R as Redis
    
    C->>G: Request User Info
    G->>A: Validate Token
    A->>R: Check Token Cache
    R-->>A: Token Valid
    A-->>G: Auth Success
    
    G->>U: Get User Info
    U->>R: Check User Cache
    alt Cache Exists
        R-->>U: Return User Data
    else Cache Miss
        U->>D: Query Database
        D-->>U: Return User Info
        U->>R: Update Cache
    end
    
    U-->>G: Return User Info
    G-->>C: Respond User Data

Flowchart di business

mermaid

flowchart TD
    Start([User Order]) --> Check{Check Stock}
    Check -->|In Stock| Reserve[Reserve Stock]
    Check -->|Out of Stock| OutOfStock[Out of Stock]
    OutOfStock --> Notify[Notify User]
    Notify --> End1([End])
    
    Reserve --> Payment{Payment Processing}
    Payment -->|Success| ConfirmOrder[Confirm Order]
    Payment -->|Fail| ReleaseStock[Release Stock]
    ReleaseStock --> PaymentFailed[Payment Failed]
    PaymentFailed --> End2([End])
    
    ConfirmOrder --> UpdateInventory[Update Inventory]
    UpdateInventory --> SendNotification[Send Notification]
    SendNotification --> Logistics[Arrange Logistics]
    Logistics --> End3([Order Complete])
    
    style Start fill:#e8f5e8
    style End1 fill:#ffebee
    style End2 fill:#ffebee
    style End3 fill:#e8f5e8
    style OutOfStock fill:#ffebee
    style PaymentFailed fill:#ffebee

Stili e temi

Stili dei nodi

mermaid

flowchart LR
    A[Default Style] --> B[Style 1]
    A --> C[Style 2]
    A --> D[Style 3]
    
    style B fill:#f9f,stroke:#333,stroke-width:4px
    style C fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
    style D fill:#f96,stroke:#333,stroke-width:4px,color:#fff

Stili di classe

mermaid

flowchart LR
    A[Node A]:::classA --> B[Node B]:::classB
    A --> C[Node C]:::classC
    
    classDef classA fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef classB fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef classC fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px

Configurazione e compatibilità

Configurazione VitePress

javascript

// .vitepress/config.js
export default {
  markdown: {
    mermaid: true
  }
}

Supporto GitHub

GitHub supporta nativamente Mermaid, puoi usarlo direttamente nei file Markdown:

markdown

```mermaid
graph LR
    A --> B


### Supporto su altre piattaforme

| Piattaforma   | Supporto    | Requisiti di configurazione |
|--------------|-------------|----------------------------|
| **GitHub**   | ✅ Nativo    | Nessuno                    |
| **GitLab**   | ✅ Nativo    | Nessuno                    |
| **VitePress**| ✅ Plugin    | Richiede configurazione     |
| **Jekyll**   | ✅ Plugin    | Installare plugin           |
| **Hugo**     | ✅ Tema      | Dipende dal tema            |

## Best practice

### Suggerimenti di design

```markdown
✅ Consigliato:

1. **Mantieni la semplicità:**
   - Evita diagrammi troppo complessi
   - Usa etichette e collegamenti chiari

2. **Layout logico:**
   - Scegli la direzione del diagramma più adatta
   - Mantieni chiaro il flusso logico

3. **Stile coerente:**
   - Usa un tema di colori coerente
   - Mantieni uno stile uniforme

4. **Aggiungi spiegazioni:**
   - Aggiungi titoli ai diagrammi complessi
   - Fornisci spiegazioni testuali necessarie

❌ Evita:

1. Diagrammi troppo complessi da capire
2. Troppe linee incrociate
3. Etichette poco chiare
4. Legenda mancante

Considerazioni sulle prestazioni

markdown

- **Ottimizzazione diagrammi grandi:**
  - Considera di suddividere i diagrammi complessi
  - Usa subgraph per organizzare

- **Prestazioni di caricamento:**
  - Evita troppi diagrammi in una sola pagina
  - Considera il lazy loading

- **Adattamento mobile:**
  - Assicurati che i diagrammi siano leggibili su schermi piccoli
  - Considera lo scorrimento orizzontale

Sintassi correlata

Incorpora HTML - Estensioni HTML
Formule matematiche - Espressioni LaTeX
Best practice - Suggerimenti di scrittura

Strumenti e risorse

Editor online

Mermaid Live Editor: Editor online ufficiale
Draw.io: Strumento diagrammi generico
Lucidchart: Piattaforma diagrammi professionale
Excalidraw: Diagrammi stile disegno a mano

Strumenti per sviluppatori

Mermaid CLI: Strumento da linea di comando
VS Code Mermaid: Estensione Visual Studio Code
Atom Mermaid: Estensione editor Atom
IntelliJ Mermaid: Estensione JetBrains IDE

Riferimenti

Mermaid Official Docs: Riferimento sintassi completo
Mermaid Example Library: Vari esempi di diagrammi
GitHub Mermaid: Utilizzo su GitHub
Awesome Mermaid: Raccolta risorse

Padroneggiando la sintassi dei flowchart, puoi creare diagrammi visivi professionali nella documentazione, migliorando chiarezza ed espressività.

Diagrammi ​

Introduzione a Mermaid ​

Sintassi di base ​

Flowchart ​

Diagramma di sequenza ​

Dettagli Flowchart ​

Tipi di nodo ​

Tipi di collegamento ​

Controllo direzione ​

Dettagli diagramma di sequenza ​

Sintassi di base ​

Barre di attivazione e lifeline ​

Cicli e condizioni ​

Diagramma delle classi ​

Diagramma degli stati ​

Gantt Chart ​

Grafico a torta ​

User Journey ​

Git Graph ​

Scenari reali ​

Schema architettura di sistema ​

Flusso chiamata API ​

Flowchart di business ​

Stili e temi ​

Stili dei nodi ​

Stili di classe ​

Configurazione e compatibilità ​

Configurazione VitePress ​

Supporto GitHub ​

Considerazioni sulle prestazioni ​

Sintassi correlata ​

Strumenti e risorse ​

Editor online ​

Strumenti per sviluppatori ​

Riferimenti ​

Diagrammi

Introduzione a Mermaid

Sintassi di base

Flowchart

Diagramma di sequenza

Dettagli Flowchart

Tipi di nodo

Tipi di collegamento

Controllo direzione

Dettagli diagramma di sequenza

Sintassi di base

Barre di attivazione e lifeline

Cicli e condizioni

Diagramma delle classi

Diagramma degli stati

Gantt Chart

Grafico a torta

User Journey

Git Graph

Scenari reali

Schema architettura di sistema

Flusso chiamata API

Flowchart di business

Stili e temi

Stili dei nodi

Stili di classe

Configurazione e compatibilità

Configurazione VitePress

Supporto GitHub

Considerazioni sulle prestazioni

Sintassi correlata

Strumenti e risorse

Editor online

Strumenti per sviluppatori

Riferimenti