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:
flowchart TDsignifica dall'alto verso il basso. UsaLRper da sinistra a destra. Anche la parolagraphfunziona al posto diflowchart.Start[Scrivi la nota]crea un riquadro.Startè il nome breve. Il testo tra parentesi quadre è l'etichetta.- Le parentesi graffe
{ }creano la forma di una decisione, un rombo. -->disegna una freccia. Il testo tra barre verticali, come|Sì|, dà un'etichetta alla freccia.
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
```
participant U as Utentecrea una colonna chiamata Utente. Il nome breve èU.->>è una freccia continua.-->>è una freccia tratteggiata, spesso usata per le risposte.- Il testo dopo i due punti è il messaggio.
- I messaggi sono disegnati dall'alto verso il basso, nell'ordine in cui li scrivi.
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:
- Diagramma di Gantt: attività su una linea temporale.
- Diagramma delle classi: le classi nel codice e come sono collegate.
- Diagramma di stato: gli stati di un elemento e come passa dall'uno all'altro.
- Diagramma entità-relazione: tabelle di database e collegamenti.
- User journey: i passaggi che compie una persona.
- Mappa mentale: idee che si ramificano da un centro.
- Cronologia: eventi in ordine di data.
- Grafo Git: rami e commit.
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
- Un piccolo errore di battitura rompe tutto il diagramma. Parole chiave sconosciute o scritte male ne impediscono il disegno. Se vedi un errore o testo semplice, controlla prima la prima riga e le frecce.
- Caratteri speciali nelle etichette. Parentesi e caratteri simili possono confondere l'analizzatore. Metti l'etichetta tra virgolette:
A["Save (draft)"]. - La parola
endin un diagramma di flusso. In minuscolo,endrompe un diagramma di flusso. ScriviEndoEND, oppure metti la parola tra virgolette. Può causare problemi anche nei diagrammi di sequenza. - Recinzione sbagliata. Il linguaggio dopo gli apici inversi deve essere
mermaid. Senza di esso, il lettore vede un normale blocco di codice.
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)