Come aprire un file .mmd

Cosa vedi

No diagram type detected matching given configuration for text: ```mermaid

Perché

Hai copiato il diagramma da un file Markdown o da una chat e ti sei portato dietro i delimitatori. I tre apici inversi sono Markdown, non Mermaid, quindi il parser non arriva mai al diagramma.

Soluzione

Togli la riga di apertura ```mermaid e quella di chiusura ```. Il file deve iniziare con una parola chiave di diagramma.

```mermaid
flowchart TD
    A[Inizio] --> B[Fine]
```

flowchart TD
    A[Inizio] --> B[Fine]

Cosa vedi

Parse error, il messaggio finisce con: got 'PS'

L'errore finisce con: got 'PS'

Perché

Una parentesi tonda aperta dentro l'etichetta di un nodo. In Mermaid le tonde sono sintassi di forma — A(testo) è un nodo arrotondato — quindi una tonda nuda dentro le quadre viene letta come l'inizio di una forma.

Soluzione

Metti l'etichetta fra virgolette. Tutto ciò che sta fra virgolette è trattato come testo, parentesi comprese.

flowchart TD
    A[Chiama addebita(ordine)] --> B[Fine]

flowchart TD
    A["Chiama addebita(ordine)"] --> B[Fine]

Cosa vedi

Parse error sulla riga in cui hai dato un nome al nodo

Perché

L'identificatore del nodo contiene uno spazio. In italiano è l'errore più facile da fare, perché i nomi naturali sono formati da più parole: «servizio di autenticazione», «base dati». L'identificatore è il token che precede la freccia, e lo spazio lo tronca lasciando una parola che non ha dove stare.

Soluzione

Dai al nodo un identificatore di una parola sola e metti il testo leggibile nell'etichetta. Verificato: accenti e apostrofo funzionano in un identificatore — `L'ordine` e `Città` si disegnano senza problemi. Rompe solo lo spazio.

flowchart TD
    servizio di autenticazione --> base dati

flowchart TD
    auth[Servizio di autenticazione] --> db[Base dati]

Cosa vedi

Parse error, il messaggio finisce con: got 'STR'

L'errore finisce con: got 'STR'

Perché

Una virgoletta doppia dritta dentro l'etichetta di un nodo. Il parser la prende per l'inizio di una stringa e poi incontra la quadra dell'etichetta dove si aspettava la virgoletta di chiusura.

Soluzione

Racchiudi l'intera etichetta fra virgolette dritte e usa dentro le caporali, oppure scrivi il carattere come entità HTML #quot;.

flowchart TD
    A[Ha detto "va bene"] --> B[Fine]

flowchart TD
    A["Ha detto «va bene»"] --> B[Fine]

Cosa vedi

Parse error, il messaggio finisce con: got 'end'

L'errore finisce con: got 'end'

Perché

Hai usato end come identificatore di nodo. In minuscolo end chiude un sottografo, quindi il parser vede la fine di un blocco dove si aspettava un nodo. Capita spesso: seguendo esempi in inglese, l'ultimo nodo finisce per chiamarsi end anche se il resto è in italiano.

Soluzione

Scrivilo con la maiuscola oppure dai al nodo un altro identificatore e sposta la parola nell'etichetta. `Fine` non crea problemi.

flowchart TD
    A[Inizio] --> end

flowchart TD
    A[Inizio] --> Fine[Completato]

Cosa vedi

Si disegna, ma in un diagramma di stato uno stato è diventato più caselle

Perché

Uno spazio nell'identificatore di uno stato. A differenza del diagramma di flusso, il diagramma di stato non protesta: crea una casella separata per ogni parola e la disegna senza batter ciglio. Misurato — `[*] --> In attesa di pagamento` produce quattro stati, `In`, `attesa`, `di` e `pagamento`, e solo il primo è in fondo alla freccia. In italiano quasi nessun nome di stato sta in una parola sola, quindi l'errore capita di continuo e non dà alcun segnale.

Soluzione

Dichiara lo stato con `state "Etichetta" as id` e riferisciti a esso solo con l'identificatore.

stateDiagram-v2
    [*] --> In attesa di pagamento
    In attesa di pagamento --> Chiuso

stateDiagram-v2
    state "In attesa di pagamento" as attesaPagamento
    [*] --> attesaPagamento
    attesaPagamento --> Chiuso

Cosa vedi

Si disegna, ma il diagramma ER ha entità che non hai scritto

Perché

L'etichetta della relazione contiene uno spazio e non ha le virgolette. È la trappola che in italiano dà più fastidio, perché le nostre espressioni relazionali reggono una preposizione: «appartiene a», «compare in». Mermaid non segnala errori: tronca l'etichetta al primo spazio e trasforma ogni parola rimasta in un'entità vuota.

Soluzione

Metti fra virgolette ogni etichetta di relazione che contenga uno spazio. In italiano praticamente tutte.

erDiagram
    CLIENTE ||--o{ ORDINE : appartiene a

erDiagram
    CLIENTE ||--o{ ORDINE : "appartiene a"

Cosa vedi

No diagram type detected matching given configuration for text: sequencediagram

Perché

La parola chiave del diagramma è scritta male o con le maiuscole sbagliate. Le parole chiave di Mermaid distinguono maiuscole e minuscole: sequenceDiagram funziona, sequencediagram no. Lo stesso vale per stateDiagram-v2 ed erDiagram.

Soluzione

Correggi le maiuscole. Nota che graph è ancora accettato come vecchio alias di flowchart, quindi quella sintassi datata non è un tuo problema.

sequencediagram
    Client->>API: Ciao

sequenceDiagram
    Client->>API: Ciao

Cosa vedi

Parse error nell'etichetta dell'arco fra le barre

Perché

Parentesi dentro l'etichetta di un arco. L'etichetta |...| ha lo stesso vincolo di quella di un nodo: anche lì le parentesi sono sintassi, non testo.

Soluzione

Metti fra virgolette l'etichetta dell'arco.

flowchart TD
    A -->|sì (sempre)| B

flowchart TD
    A -->|"sì (sempre)"| B

Cosa vedi

Parse error che indica l'ultima riga del diagramma

Perché

Un blocco aperto e mai chiuso: alt, opt, loop, par e subgraph vogliono il loro end. Mermaid segnala l'errore dove gli finisce l'input, quindi il numero di riga indica la fine del file e non il blocco aperto.

Soluzione

Conta i blocchi aperti e gli end che hai scritto. Se l'errore indica l'ultima riga, è quasi sempre questo.

sequenceDiagram
    Client->>API: Richiesta
    alt Tutto a posto
        API-->>Client: OK

sequenceDiagram
    Client->>API: Richiesta
    alt Tutto a posto
        API-->>Client: OK
    end

Cosa vedi

Lexical error on line 1. Unrecognized text.

Perché

Direzione non valida dopo la parola chiave del diagramma. I diagrammi di flusso accettano TB, TD, BT, LR e RL, e nient'altro; un refuso cade nell'analisi lessicale prima che venga letto anche un solo nodo.

Soluzione

Usa una delle cinque direzioni valide. TD e LR coprono quasi tutti i casi.

flowchart XY
    A --> B

flowchart TD
    A --> B

Cosa vedi

Qui si disegna, su GitLab, Confluence o su un vecchio strumento no

Perché

Differenza di versione. Questo visualizzatore gira su Mermaid 11.12.2; GitLab.com documenta la versione 10, e le wiki installate in proprio possono essere indietro di anni. La sintassi introdotta dopo la versione dell'altro strumento si analizza qui e cade là.

Soluzione

Chiedi all'altro motore la sua versione. Scrivere la sola parola info in un diagramma fa disegnare a Mermaid il proprio numero di versione, il che è più rapido che leggere il registro delle modifiche.

info