Comment intégrer des diagrammes Mermaid
Certains outils dessinent Mermaid à votre place à partir de texte brut ; d'autres ont besoin d'une image exportée. Voici où il s'affiche nativement, comment l'intégrer sur chaque plateforme, et la solution de repli quand un outil n'en est pas capable.
- 01
Construire le diagramme
Ouvrez l'éditeur, écrivez ou collez votre Mermaid, et vérifiez qu'il s'affiche comme vous le souhaitez.
- 02
Copier la source ou exporter une image
Pour les plateformes qui affichent Mermaid nativement, copiez le bloc Markdown délimité ```mermaid. Partout ailleurs, exportez un SVG ou un PNG.
- 03
Le coller au bon endroit
Collez le bloc Mermaid dans une plateforme native, ou déposez l'image exportée dans un document, une diapositive ou un e-mail. Conservez la source dans votre dépôt pour qu'elle reste modifiable.
Où Mermaid s'affiche — plateforme par plateforme
| Plateforme | Prise en charge de Mermaid | Comment l'intégrer |
|---|---|---|
| GitHub | Native | Collez un bloc délimité ```mermaid dans n'importe quel README, fichier Markdown, ticket, pull request, discussion ou wiki. GitHub le dessine automatiquement. |
| GitLab | Native | Le même bloc délimité ```mermaid fonctionne dans le Markdown, les tickets et les merge requests sur GitLab.com comme sur les instances auto-hébergées. |
| Obsidian | Native | Écrivez un bloc de code ```mermaid dans n'importe quelle note ; Obsidian l'affiche en mode lecture et en aperçu en direct — aucune extension nécessaire. |
| Notion | Native (bloc de code) | Insérez un bloc /code, définissez son langage sur « Mermaid », collez la source, puis utilisez la vue Preview / Split du bloc pour afficher le diagramme. |
| Confluence | Nécessite une application | Confluence n'intègre pas Mermaid par défaut. Installez une application du Marketplace (par exemple une macro Mermaid) et collez-y la source, ou intégrez un SVG/PNG exporté. |
| Votre propre site web | Native (ajouter le script) | Déposez la source dans une balise "pre" avec la classe "mermaid" et chargez mermaid.js depuis un CDN — voir l'extrait ci-dessous. Ou intégrez un SVG exporté pour zéro JavaScript. |
| Slack, Google Docs, e-mail, PDF | Exporter une image | Ces outils n'affichent pas Mermaid. Exportez un SVG (net à toute taille) ou un PNG depuis l'éditeur et collez cette image. |
Les fonctionnalités des plateformes évoluent — vérifiez sur votre propre compte, en particulier pour les aperçus Notion et les applications Confluence. « Native » signifie que le diagramme s'affiche à partir de la source sans téléversement d'image.
Intégrer sur votre propre site web
Collez la source Mermaid dans un élément "pre" avec la classe "mermaid" et chargez le moteur de rendu depuis un CDN. Voici l'intégration ESM officielle — copiez-la telle quelle :
<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>Figez une version majeure (ici mermaid@11) pour qu'une future version ne puisse pas modifier vos diagrammes de façon inattendue. Pour une page statique sans JavaScript, exportez un SVG depuis l'éditeur et référencez-le comme une image à la place.
README GitHub, étape par étape
GitHub est la cible la plus courante. Pour le guide complet — y compris la raison pour laquelle un bloc s'affiche parfois sous forme de code plutôt que de diagramme — consultez comment intégrer un diagramme Mermaid dans un README GitHub.
Créez d'abord un diagramme : ouvrir l'éditeur Mermaid, exemples prêts à l'emploi.
Questions fréquemment posées
Quelles plateformes affichent Mermaid sans extension ?
GitHub, GitLab et Obsidian affichent nativement les blocs délimités ```mermaid. Notion l'affiche dans un bloc de code défini sur le langage Mermaid avec sa vue d'aperçu. La plupart des autres outils — Slack, Google Docs, e-mail — ont besoin d'une image SVG ou PNG exportée à la place.
Comment intégrer un diagramme Mermaid dans Notion ?
Ajoutez un bloc de code (tapez /code), changez son langage en « Mermaid » et collez la source de votre diagramme. Notion affiche un bouton Preview / Split sur le bloc qui rend le diagramme. Pour une copie statique, exportez une image depuis l'éditeur et intégrez-la à la place.
Comment afficher un diagramme Mermaid sur mon propre site web ?
Placez la source dans un élément "pre" avec la classe "mermaid" et chargez mermaid.js depuis un CDN avec mermaid.initialize({ startOnLoad: true }). L'extrait sur cette page est un exemple complet et fonctionnel. Si vous préférez ne livrer aucun JavaScript, exportez un SVG et utilisez-le comme image.
Dois-je intégrer la source ou une image exportée ?
Là où la plateforme affiche Mermaid (GitHub, GitLab, Obsidian, votre propre site), intégrez la source — elle reste modifiable et comparable dans le contrôle de version. Là où ce n'est pas le cas, exportez un SVG ou un PNG. Le SVG s'adapte sans flou ; le PNG convient aux diapositives.
Confluence prend-il en charge Mermaid ?
Pas d'emblée. Il vous faut une application du Marketplace qui ajoute une macro Mermaid, ou vous pouvez coller une image SVG/PNG exportée. Vérifiez auprès de votre administrateur Confluence l'application que vous êtes autorisé à installer.