mermaid markdown diagrams flowchart documentation

Mermaid in Markdown: creare diagrammi di flusso, di sequenza e altro

Impara la sintassi di Mermaid per Markdown con esempi di diagrammi di flusso, sequenze, classi, Gantt, mappe mentali e diagrammi ER pronti per la copia, oltre a indicazioni su anteprima, esportazione, compatibilità e accessibilità.

W
WordToMD Squadra
·

Gli schemi tecnici spesso diventano obsoleti perché per modificarli è necessario trovare il file di disegno originale, aprire un'applicazione separata ed esportare un'altra immagine.Mermaid adotta un approccio diverso: il diagramma è definito come testo e memorizzato accanto alla documentazione.

Per sommare Mermaid a Markdown posizionare la definizione dello schema all'interno di un blocco di codice recintato con mermaid Identificatore della lingua.Usa il Anteprima diagrammi Mermaid per rendere la sintassi localmente, correggere errori, copiare il recinto completo Markdown o scaricare un SVG.

Questa guida inizia con un piccolo diagramma di flusso e si sviluppa verso sequenze, classi, Gantt, mappe mentali e diagrammi di relazioni tra entità.

Mermaid in 30 Secondi

Un blocco base Mermaid si presenta così:

```mermaid
flowchart LR
  Draft --> Review
  Review --> Publish
```

La recinzione di apertura indica a un renderer compatibile che il contenuto ha la sintassi Mermaid. flowchart LR seleziona un diagramma di flusso disposto da sinistra a destra.Le restanti linee definiscono nodi e connessioni.

Se la destinazione non supporta Mermaid, i lettori vedranno solitamente un blocco di codice invece di un diagramma.Questo fallback preserva la fonte, ma non sostituisce il controllo della compatibilità prima della pubblicazione.

Perché utilizzare diagrammi basati su testo?

Mermaid è particolarmente utile quando uno schema:

  • appartiene alla documentazione con controllo della versione;
  • modifiche del codice o delle procedure;
  • necessita di differenze pull-request significative;
  • utilizza forme e relazioni standard;
  • dovrebbe essere modificabile senza un file di progettazione proprietario;
  • deve essere rigenerato in temi chiari e scuri.

È meno adatto per illustrazioni dettagliate, layout pixel-perfect, annotazioni a mano libera o design visivo che richiedono un posizionamento manuale preciso.In questi casi, utilizza uno strumento di disegno ed esporta un SVG o un'immagine accessibile.

Esempio 1: un diagramma di flusso

I diagrammi di flusso descrivono un processo, una decisione o una regola di instradamento.

```mermaid
flowchart TD
  A[Choose a DOCX file] --> B{File valid?}
  B -->|Yes| C[Convert to Markdown]
  B -->|No| D[Show an error]
  C --> E[Review the output]
  E --> F[Copy or download]
```

Sintassi chiave:

  • TD significa dall'alto verso il basso.
  • LR significa da sinistra a destra.
  • [Text] crea un nodo di processo rettangolare.
  • {Text} crea un nodo decisionale.
  • --> crea un collegamento direzionale.
  • -->|Label| aggiunge del testo ad una connessione.

Utilizzare ID nodo stabili e brevi come A or validate.Mantenere l'etichetta visibile tra parentesi in modo che la modifica del testo non richieda la modifica di ogni connessione.

Aggiungere un sottografo

Passaggi relativi al gruppo sottografi:

```mermaid
flowchart LR
  subgraph Browser
    Upload[Choose file] --> Convert[Convert locally]
  end

  subgraph Output
    Preview[Preview Markdown] --> Save[Download file]
  end

  Convert --> Preview
```

Utilizzare i sottografi quando il raggruppamento comunica proprietà, confini del sistema o fasi.Non aggiungere una scatola solo per la decorazione.

Esempio 2: un diagramma di sequenza

I diagrammi di sequenza mostrano le interazioni in ordine temporale.Funzionano bene per chiamate da API, autenticazione, flussi di lavoro del browser e sistemi basati su eventi.

```mermaid
sequenceDiagram
  autonumber
  actor User
  participant Browser
  participant Converter

  User->>Browser: Select DOCX file
  Browser->>Converter: Pass local file data
  Converter-->>Browser: Return Markdown
  Browser-->>User: Show editable preview
```

Frecce comuni:

  • ->> invia un messaggio solido.
  • -->> invia una risposta tratteggiata.
  • participant dichiara un sistema o un servizio.
  • actor dichiara un ruolo umano o esterno.
  • autonumber etichetta le interazioni in ordine.

Focus su uno scenario.Un diagramma di sequenza che tenta di mostrare ogni alternativa e ogni funzione interna diventa più difficile da comprendere rispetto al codice.

Mostrare un percorso alternativo

```mermaid
sequenceDiagram
  participant Client
  participant API

  Client->>API: POST /documents
  alt Valid request
    API-->>Client: 201 Created
  else Invalid request
    API-->>Client: 400 Bad Request
  end
```

Utilizzo alt, else, e end per rami significativi.Se il ramo richiede diverse pagine di spiegazione, collega alla prosa sotto il diagramma.

Esempio 3: un diagramma di classi

I diagrammi delle classi descrivono tipi, proprietà, operazioni, ereditarietà e relazioni.

```mermaid
classDiagram
  class Document {
    +String name
    +String content
    +convert()
  }

  class MarkdownDocument {
    +String frontmatter
    +render()
  }

  Document <|-- MarkdownDocument
```

Questo esempio afferma che MarkdownDocument eredita da Document.Utilizzare i diagrammi delle classi per un modello concettuale, non come sostituto automatico della documentazione di riferimento completa API.

I buoni diagrammi delle classi omettono dettagli che non aiutano il lettore a comprendere il progetto.Mostrare ogni campo privato può trasformare il diagramma in una versione meno ricercabile del codice sorgente.

Esempio 4: un diagramma di Gantt

I diagrammi di Gantt mostrano le attività nel tempo.Sono utili per piani di rilascio, migrazioni e progetti di documentazione.

```mermaid
gantt
  title Documentation migration
  dateFormat YYYY-MM-DD

  section Preparation
  Inventory content :done, inventory, 2026-11-03, 3d
  Define templates  :done, templates, after inventory, 2d

  section Migration
  Convert documents :active, convert, 2026-11-08, 7d
  Editorial review  :review, after convert, 5d

  section Publish
  Final validation  :validate, after review, 2d
```

Mantieni le date esplicite e utilizza gli ID attività quando un'attività dipende da un'altra.Ricordare che un diagramma archiviato nella documentazione non si aggiornerà automaticamente quando cambia la pianificazione del progetto reale.Assegna la proprietà per mantenerlo aggiornato.

Esempio 5: Una mappa mentale

Le mappe mentali organizzano le idee attorno a un argomento centrale.

```mermaid
mindmap
  root((Markdown quality))
    Structure
      Headings
      Lists
      Tables
    Accessibility
      Alt text
      Link text
      Reading order
    Publishing
      GitHub
      Obsidian
      Documentation site
```

Le mappe mentali sono più efficaci durante la pianificazione o come panoramica di alto livello.Sono meno utili per relazioni precise perché la struttura ad albero può implicare una gerarchia in cui i concetti reali si sovrappongono.

Esempio 6: un diagramma entità-relazione

I diagrammi ER descrivono le entità dei dati e le loro relazioni.

```mermaid
erDiagram
  AUTHOR ||--o{ DOCUMENT : writes
  DOCUMENT ||--o{ REVISION : contains
  DOCUMENT }o--o{ TAG : uses

  AUTHOR {
    string id
    string name
  }

  DOCUMENT {
    string id
    string title
    datetime published_at
  }
```

Utilizzare un diagramma ER per spiegare il modello e uno schema o un file di migrazione per definire l'implementazione.Un diagramma può omettere indici, vincoli e campi che non sono rilevanti per la spiegazione corrente.

Anteprima Mermaid Prima della pubblicazione

Scrivere diagrammi direttamente in un lungo documento Markdown rende difficile isolare gli errori di sintassi.Un ciclo di anteprima focalizzato è più veloce:

  1. Apri il... Anteprima diagrammi Mermaid.
  2. Incolla solo la definizione dello schema, senza il recinto di codice esterno.
  3. Renderizzare lo schema.
  4. Leggere eventuali errori di sintassi e correggere l'area di riferimento.
  5. Copiare il recintato Markdown generato.
  6. Scarica l'SVG quando la destinazione necessita di una risorsa statica.
  7. Testare il Markdown finale nella sua piattaforma reale.

L'anteprima viene visualizzata nel tuo browser con una rigorosa configurazione di sicurezza.I callback dei diagrammi e altri comportamenti interattivi possono essere disabilitati anche se un'altra installazione Mermaid li consente.Questo comportamento conservativo è appropriato per uno strumento di anteprima generale.

Errori comuni Mermaid

Manca il tipo di schema

Non corretto:

A --> B

Corretto:

flowchart LR
  A --> B

La prima riga identifica la grammatica del diagramma.

La punteggiatura in un'etichetta interrompe l'analisi

Etichette complesse quote:

flowchart LR
  A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]

Ciò è particolarmente utile per parentesi, punteggiatura ed etichette che assomigliano alla sintassi.

Viene utilizzato inaspettatamente un Word riservato

Le grammatiche Mermaid hanno parole chiave.La documentazione ufficiale del diagramma di flusso avverte specificamente che è minuscolo end può interrompere un diagramma di flusso.Scrivilo in maiuscolo o posiziona il testo visibile all'interno di un'etichetta del nodo tra virgolette:

flowchart LR
  Start --> Finish["End"]

La recinzione del codice non è corretta

L'identificatore della lingua si trova immediatamente dopo gli apici inversi di apertura:

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

Non rientrare l'intera recinzione a meno che la sintassi Markdown circostante non lo richieda.

Funziona su una piattaforma ma non su un'altra

Mermaid si evolve e le piattaforme possono utilizzare diversi renderer, versioni, impostazioni di sicurezza e tipi di diagrammi abilitati.Una funzionalità di sintassi supportata dalla versione più recente Mermaid potrebbe non funzionare in una piattaforma che utilizza un'altra implementazione o una versione precedente.

Preferisce la sintassi ampiamente supportata per i documenti che si spostano tra le piattaforme.Testa forme avanzate, temi, direttive e tipi di diagrammi più recenti in ogni destinazione richiesta.

Compatibilità della piattaforma

La compatibilità dovrebbe essere testata piuttosto che data per scontata:

PiattaformaApproccio attualmente documentatoNota importante
GitHubUtilizzo recintato mermaid blockRendering di documenti GitHub in file Markdown, questioni, discussioni, richieste pull e wiki
GitLabUtilizza un blocco di codice Mermaid in GitLab Flavored MarkdownGitLab documenta la versione Mermaid supportata;le installazioni autogestite possono differire
ObsidianUtilizzo recintato mermaid bloccare in una notaIl renderer di Obsidian e le funzionalità supportate possono cambiare tra una versione e l'altra
Materiale per MkDocsConfigurare una recinzione personalizzata MermaidL'integrazione del tema nativo richiede documentazione pymdownx.superfences configuration
Parser generico MarkdownSpesso visualizza solo il codiceIl rendering Mermaid di solito richiede un'integrazione JavaScript o un plugin di creazione

Controllare la documentazione ufficiale attuale prima di affidarsi a una funzionalità più recente:

Per un sito di documentazione che controlli, aggiungi la versione della dipendenza Mermaid e prova gli aggiornamenti.Altrimenti, una piccola modifica alla sintassi può alterare i diagrammi dell'intero sito.

Mermaid e Accessibilità

Un SVG renderizzato non comunica automaticamente il suo significato a ogni lettore.Tratta il diagramma come un riassunto visivo e fornisci una spiegazione equivalente in prosa vicina.

Per il diagramma di flusso di conversione precedente, aggiungere testo come:

L'utente seleziona un file DOCX.I file validi vengono convertiti localmente e visualizzati per la revisione;i file non validi producono un errore.L'utente può quindi copiare o scaricare il Markdown revisionato.

Pratiche di accessibilità:

  • introdurre quanto spiegato nello schema;
  • riassumere la conclusione dopo diagrammi complessi;
  • non codificano il significato solo con il colore;
  • utilizzare etichette leggibili anziché abbreviazioni interne;
  • mantenere un contrasto sufficiente nei temi chiari e scuri;
  • evitare schemi che richiedono un'interazione precisa del mouse;
  • fornire un testo o una tabella alternativa per le informazioni essenziali;
  • esportare SVG con attenzione quando il file statico deve avere un nome accessibile.

Il codice sorgente è utile agli autori, ma non è necessariamente una buona alternativa testuale per i lettori.

Progettare diagrammi che rimangano leggibili

Mantenere uno scopo per schema

Un diagramma dovrebbe rispondere a una domanda del tipo "Cosa succede dopo una richiesta non riuscita?"o "Quale servizio possiede ciascun archivio dati?"Se tenta di spiegare l’intero sistema, dividilo.

Preferire etichette corte

Mettere spiegazioni dettagliate in prosa.Le etichette lunghe costringono i nodi stretti, l'avvolgimento delle linee scomodo e i diagrammi di grandi dimensioni sugli schermi dei dispositivi mobili.

Utilizzare la direzione intenzionalmente

Il flusso da sinistra a destra funziona bene per processi brevi e percorsi di richiesta.Il flusso dall'alto verso il basso spesso si adatta meglio agli schermi stretti.Visualizza l'anteprima di entrambi prima di impegnarti.

Limita lo stile visivo

I colori personalizzati possono entrare in conflitto con la modalità oscura o con i temi della piattaforma.Inizia con le impostazioni predefinite del renderer.Aggiungi stili solo quando comunicano significato e rimangono leggibili in tutti i temi richiesti.

Mantenere la fonte vicino alla sua spiegazione

Memorizzare il blocco Mermaid quando possibile nello stesso file Markdown.Ciò fa sì che la prosa e il diagramma cambino insieme in un'unica recensione.

Mermaid rispetto ad un'immagine statica

Scegliere Mermaid quando:

  • il diagramma cambia frequentemente;
  • le differenze di sorgente sono preziose;
  • il layout utilizza tipologie di schemi standard;
  • la piattaforma di pubblicazione riproduce Mermaid in modo affidabile.

Scegliere SVG o PNG quando:

  • la progettazione richiede una precisa impaginazione manuale;
  • la destinazione non rende Mermaid;
  • l'aspetto esatto deve rimanere fisso;
  • la condivisione esterna richiede una risorsa autonoma.

Un ibrido utile è mantenere l'origine Mermaid ed esportare un SVG per le destinazioni che non possono renderizzarlo.Conserva l'origine accanto alla risorsa esportata e documenta come rigenerarla.

Utilizzo Markdown in immagine per contenuti renderizzati Markdown condivisibili oppure scaricare SVG direttamente dal Anteprima diagrammi Mermaid quando l'asset è lo schema stesso.

FAQ

Mermaid fa parte dello standard Markdown?

N. A recintato mermaid block è un'estensione riconosciuta dalle applicazioni e dai sistemi di build compatibili.Un parser di base Markdown può renderlo come codice ordinario.

GitHub rende i diagrammi Mermaid?

Sì.La documentazione di GitHub descrive il rendering Mermaid nei file Markdown e diverse superfici di collaborazione.Testare la sintassi più recente perché GitHub controlla il renderer distribuito e le impostazioni di sicurezza.

Posso utilizzare Mermaid in Obsidian?

La guida ufficiale di Obsidian documenta blocchi di diagrammi recintati in stile Mermaid nelle note.Il supporto delle funzionalità può cambiare con il renderer dell'applicazione, quindi verifica i tipi di diagrammi complessi o appena introdotti nella versione installata.

Mermaid può sostituire la documentazione di architettura?

No. Un diagramma è una vista di un sistema.Abbinalo a decisioni, proprietà, vincoli, comportamenti in caso di errore e collegamenti a interfacce o schemi autorevoli.

Perché il mio diagramma viene visualizzato in modo diverso in modalità oscura?

Le piattaforme possono applicare temi Mermaid, variabili CSS, caratteri e sfondi diversi.Evita i colori hardcoded finché non hai testato entrambi i temi.

Devo salvare i file SVG esportati?

Effettuare il commit di un SVG quando la destinazione di pubblicazione necessita di una risorsa statica o il risultato renderizzato deve rimanere stabile.Conservare inoltre la sorgente Mermaid e un processo di rigenerazione documentato per evitare che le due versioni vadano alla deriva.

Mermaid è sicuro per schemi riservati?

La riservatezza dipende dall'editor e dal flusso di lavoro di pubblicazione.L'anteprima di WordToMD esegue il rendering del diagramma nel tuo browser, ma la pubblicazione di Markdown o SVG in un repository o sito segue i controlli di accesso di quella destinazione.

Conclusioni

Mermaid rende i diagrammi mantenibili perché la sorgente convive con Markdown.Inizia con un piccolo blocco delimitato, scegli il tipo di diagramma che corrisponde alla domanda, visualizza in anteprima la sintassi e testala nel renderer finale.Utilizza la prosa per spiegare il significato essenziale ed esporta SVG quando una destinazione necessita di una risorsa statica.

Prova gli esempi nel Anteprima diagrammi Mermaid, modificare la documentazione circostante nel file Markdown Redattoree mantieni il diagramma sufficientemente focalizzato affinché un futuro contributore possa comprenderlo e aggiornarlo senza ridisegnare l'intera pagina.