Come incorporare i diagrammi Mermaid
Alcuni strumenti disegnano Mermaid al posto tuo a partire dal testo semplice; altri richiedono un'immagine esportata. Ecco dove viene renderizzato in modo nativo, come incorporarlo su ciascuna piattaforma e la soluzione di ripiego quando uno strumento non può.
- 01
Crea il diagramma
Apri l'editor, scrivi o incolla il tuo Mermaid e verifica che venga renderizzato come desideri.
- 02
Copia il sorgente o esporta un'immagine
Per le piattaforme che renderizzano Mermaid in modo nativo, copia il blocco Markdown delimitato ```mermaid. Per tutto il resto, esporta un SVG o un PNG.
- 03
Incollalo dove va
Incolla il blocco Mermaid in una piattaforma nativa, oppure inserisci l'immagine esportata in un documento, una slide o un'email. Conserva il sorgente nel tuo repository in modo che rimanga modificabile.
Dove Mermaid viene renderizzato — piattaforma per piattaforma
| Piattaforma | Supporto Mermaid | Come incorporare |
|---|---|---|
| GitHub | Nativo | Incolla un blocco delimitato ```mermaid in qualsiasi README, file Markdown, issue, pull request, discussione o wiki. GitHub lo disegna automaticamente. |
| GitLab | Nativo | Lo stesso blocco delimitato ```mermaid funziona in Markdown, issue e merge request su GitLab.com e nelle istanze self-managed. |
| Obsidian | Nativo | Scrivi un blocco di codice ```mermaid in qualsiasi nota; Obsidian lo renderizza nelle modalità di lettura e anteprima dal vivo — nessun plugin necessario. |
| Notion | Nativo (blocco di codice) | Inserisci un blocco /code, imposta il suo linguaggio su "Mermaid", incolla il sorgente, quindi usa la vista Anteprima / Divisa del blocco per mostrare il diagramma. |
| Confluence | Richiede un'app | Confluence non ha un Mermaid integrato. Installa un'app dal Marketplace (ad es. una macro Mermaid) e incolla il sorgente al suo interno, oppure incorpora un SVG/PNG esportato. |
| Il tuo sito web | Nativo (aggiungi lo script) | Inserisci il sorgente in un tag "pre" con classe "mermaid" e carica mermaid.js da una CDN — vedi lo snippet qui sotto. Oppure incorpora un SVG esportato per zero JavaScript. |
| Slack, Google Docs, email, PDF | Esporta un'immagine | Questi non renderizzano Mermaid. Esporta un SVG (nitido a qualsiasi dimensione) o un PNG dall'editor e incolla quell'immagine. |
Le funzionalità delle piattaforme cambiano — verifica sul tuo account, in particolare per le anteprime di Notion e le app di Confluence. "Nativo" significa che il diagramma viene renderizzato dal sorgente senza alcun caricamento di immagini.
Incorporare nel tuo sito web
Incolla il sorgente Mermaid in un elemento "pre" con la classe "mermaid" e carica il renderer da una CDN. Questo è l'embed ESM ufficiale — copialo così com'è:
<pre class="mermaid">
flowchart TD
A[Start] --> B{OK?}
B -->|Yes| C[Ship]
B -->|No| A
</pre>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>Fissa una versione major (qui mermaid@11) in modo che una futura release non possa modificare i tuoi diagrammi in modo inaspettato. Per una pagina statica senza JavaScript, esporta un SVG dall'editor e fai riferimento ad esso come immagine.
README di GitHub, passo per passo
GitHub è la destinazione più comune. Per la guida completa — incluso il motivo per cui a volte un blocco viene mostrato come codice anziché come diagramma — vedi come incorporare un diagramma Mermaid in un README di GitHub.
Crea prima un diagramma: apri l'editor Mermaid, esempi pronti all'uso.
Domande frequenti
Quali piattaforme renderizzano Mermaid senza un plugin?
GitHub, GitLab e Obsidian renderizzano in modo nativo i blocchi delimitati ```mermaid. Notion lo renderizza all'interno di un blocco di codice impostato sul linguaggio Mermaid con la sua vista anteprima. La maggior parte degli altri strumenti — Slack, Google Docs, email — richiede invece un'immagine SVG o PNG esportata.
Come incorporo un diagramma Mermaid in Notion?
Aggiungi un blocco di codice (digita /code), cambia il suo linguaggio in "Mermaid" e incolla il sorgente del tuo diagramma. Notion mostra sul blocco un interruttore Anteprima / Divisa che renderizza il diagramma. Per una copia statica, esporta un'immagine dall'editor e incorpora quella invece.
Come mostro un diagramma Mermaid sul mio sito web?
Inserisci il sorgente all'interno di un elemento "pre" con classe "mermaid" e carica mermaid.js da una CDN con mermaid.initialize({ startOnLoad: true }). Lo snippet in questa pagina è un esempio completo e funzionante. Se preferisci non spedire alcun JavaScript, esporta un SVG e usalo come immagine.
Conviene incorporare il sorgente o un'immagine esportata?
Dove la piattaforma renderizza Mermaid (GitHub, GitLab, Obsidian, il tuo sito), incorpora il sorgente — rimane modificabile e confrontabile nel controllo di versione. Dove non lo fa, esporta un SVG o un PNG. L'SVG si ridimensiona senza sfocature; il PNG è adatto alle slide.
Confluence supporta Mermaid?
Non di default. Hai bisogno di un'app dal Marketplace che aggiunga una macro Mermaid, oppure puoi incollare un'immagine SVG/PNG esportata. Verifica con l'amministratore di Confluence quale app ti è consentito installare.