Diagrammi Mermaid in Markdown

Mermaid è un modo per disegnare diagrammi con il testo. Scrivi poche righe brevi. Un lettore che supporta Mermaid le trasforma in un'immagine: un diagramma di flusso, una cronologia, un grafico.

Puoi tenere il diagramma dentro un normale file Markdown. Non c'è nessuna immagine da esportare e nessuno strumento di disegno da aprire. Per cambiare il diagramma, cambi il testo.

Il blocco di codice mermaid

Un diagramma Mermaid vive in un blocco di codice delimitato. Una recinzione sono tre apici inversi. Dopo la recinzione di apertura, scrivi mermaid come linguaggio:

```mermaid
flowchart LR
    A --> B
```

La prima riga dentro il blocco dice di che tipo di diagramma si tratta. Qui è flowchart LR. Tutto ciò che segue quella riga descrive il diagramma.

Le righe che iniziano con %% sono commenti. Il lettore le ignora.

Esempio 1: un diagramma di flusso con una decisione

```mermaid
flowchart TD
    Start[Scrivi la nota] --> Check{È chiara?}
    Check -->|Sì| Publish[Condividila]
    Check -->|No| Edit[Riscrivila]
    Edit --> Check
```

Come leggerlo:

Esempio 2: un diagramma di sequenza

Un diagramma di sequenza mostra chi parla con chi, in ordine.

```mermaid
sequenceDiagram
    participant U as Utente
    participant S as Server
    U->>S: Apri la pagina
    S-->>U: Invia la pagina
    U->>S: Accedi
    S-->>U: Benvenuto
```

Esempio 3: un grafico a torta

```mermaid
pie title Tempo dedicato a un progetto
    "Scrittura" : 40
    "Lettura" : 25
    "Riunioni" : 15
    "Altro" : 20
```

Ogni spicchio è un'etichetta tra virgolette, i due punti e un numero. Il numero deve essere maggiore di zero.

Altri tipi di diagramma

Mermaid può disegnare molti altri tipi. I più comuni:

Ogni tipo ha una propria prima parola e proprie regole. La documentazione di Mermaid ha una pagina per ciascuno.

Dove vengono disegnati i diagrammi Mermaid

GitHub disegna i blocchi Mermaid nei file Markdown, nelle issue, nelle discussioni, nelle pull request e nei wiki. Ti basta il blocco di codice mermaid. Anche molti editor Markdown e app di note supportano Mermaid, ma non tutti.

Quando un lettore non supporta Mermaid, di solito tratta il blocco come qualsiasi altro codice. Vedi il testo che hai scritto, non un'immagine. Non si perde nulla. Semplicemente non viene disegnato.

Errori comuni

Non serve il rientro. La maggior parte delle persone fa rientrare le righe dentro un diagramma solo perché è più facile da leggere.

Le chat IA e gli agenti scrivono Mermaid

Le chat IA e gli agenti di programmazione inseriscono spesso Mermaid in pianificazioni, specifiche e note di progettazione. Un diagramma di flusso è un modo rapido per mostrare i passaggi. Un diagramma di sequenza mostra come parlano tra loro le parti di un sistema.

Se una chat ti dà un diagramma, copia l'intero blocco di codice, recinzioni comprese, nel tuo file Markdown. Se il diagramma non viene disegnato, confrontalo con gli errori qui sopra. Etichette brevi e un'idea per diagramma rendono il testo più facile da correggere.

Leggere i diagrammi Mermaid

PilcrowMD disegna i diagrammi Mermaid su Android e su Mac, senza bisogno di internet. Su Android, tocca un diagramma per vederlo a schermo intero. Su Mac, Quick Look, Confronta e PDF mostrano il blocco di codice invece dell'immagine.

Domande frequenti

Devo installare qualcosa per scrivere Mermaid? No. Scrivi testo semplice in un blocco di codice. Ti serve solo un lettore che lo disegni.

Perché vedo del codice invece di un diagramma? O il lettore non supporta Mermaid, oppure il diagramma ha un errore di sintassi. Controlla che il blocco inizi con mermaid e che la prima riga indichi un vero tipo di diagramma.

Posso cambiare l'aspetto di un diagramma? Sì. Mermaid ha opzioni per colori, forme e layout. Parti dalle impostazioni predefinite. Bastano per la maggior parte delle note.

Anche su Mac: PilcrowMD per Mac (beta)