Syntaxe des Diagrammes Mermaid : Exemples pour Markdown et Obsidian

Un diagramme Mermaid est une représentation visuelle générée à partir de code en texte brut à l’aide de la bibliothèque Mermaid JS. Créé par Knut Sveidqvist vers 2014, ce projet open source Mermaid est devenu la référence pour les diagrammes basés sur du texte dans la documentation logicielle. En 2026, les principales plateformes telles que GitHub, GitLab et divers outils de documentation intègrent nativement le rendu de la syntaxe Mermaid.

Ce guide explique la syntaxe Mermaid, les principaux types de diagrammes, le rendu dans Markdown et Obsidian, les options d’exportation ainsi que les erreurs courantes à éviter.

Voici à quoi ressemble la syntaxe de base :

graph TD
    A[Start] --> B[Process]
    B --> C[Complete]

L’approche « diagrams as code » améliore la maintenabilité grâce au contrôle de version et simplifie la collaboration au sein des équipes d’ingénierie. Les sections suivantes abordent les types de diagrammes courants, la création étape par étape et l’exportation de diagrammes pour les parties prenantes qui préfèrent les images statiques.

Anti-sèche sur la syntaxe Mermaid

Diagramme	Mot-clé d’ouverture	Utilisation typique
Organigramme (Flowchart)	flowchart TD ou flowchart LR	Processus et prises de décision
Séquence	sequenceDiagram	Requêtes, réponses et interactions de services
Entité-Association (ERD)	erDiagram	Entités et relations de base de données
État	stateDiagram-v2	Changements d’état et de cycle de vie
Gantt	gantt	Jalons et calendriers de projets
Classe	classDiagram	Modèles de domaine et d’objets

Chaque bloc Mermaid nécessite un mot-clé d’ouverture unique. Les identifiants de nœud doivent rester courts et stables ; les étiquettes visibles peuvent contenir du texte plus long et lisible.

Qu’est-ce qu’un diagramme Mermaid et pourquoi devriez-vous l’utiliser ?

Un diagramme Mermaid est généré à partir d’une syntaxe texte légère interprétée par la bibliothèque JavaScript Mermaid. Au lieu d’utiliser une interface de glisser-déposer, vous rédigez du code de diagramme Mermaid que la bibliothèque transforme en graphiques SVG.

Comment le code Mermaid devient visuel :

• graph TD; A –> B; affiche un organigramme de haut en bas

• les blocs sequenceDiagram deviennent des diagrammes de séquence montrant le flux des messages

• les définitions erDiagram génèrent des diagrammes entité-association

Principaux avantages des diagrammes textuels :

• Texte brut lisible par tous et facile à modifier

• Différentiels (diffs) compatibles avec Git montrant précisément ce qui a changé

• Revues de code facilitées dans les pull requests

• Pas de fichiers propriétaires de diagramme à gérer

Cas d’utilisation concrets pour 2026 :

• Documenter un flux d’authentification de microservices avec des diagrammes de séquence

• Cartographier des pipelines CI/CD du commit jusqu’au déploiement en production

• Planifier les jalons du lancement de produit du T2 2026 avec des diagrammes de Gantt

Les diagrammes Mermaid s’intègrent naturellement avec la documentation en Markdown, les wikis internes et les portails développeurs, simplifiant ainsi la documentation à l’échelle de l’entreprise.

Principaux types de diagrammes Mermaid

Mermaid prend en charge un large éventail de types de diagrammes. Cette section fournit un aperçu pratique des plus utiles au lieu d’une référence exhaustive.

Principaux types de diagrammes :

Type	Mot-clé	Idéal pour
Organigrammes (Flowcharts)	graph TD / flowchart LR	Flux de processus, arbres de décision
Diagrammes de séquence	sequenceDiagram	Appels API, interactions de services
Diagrammes de classes	classDiagram	Modèles d’objets, conception de domaine
Diagrammes d’état	stateDiagram-v2	États de cycle de vie, workflows
Diagrammes entité-association	erDiagram	Conception de schémas de base de données
Parcours utilisateur (Journey)	journey	Cartographie de l’expérience client
Diagrammes de Gantt	gantt	Calendriers de projet, roadmaps
Graphiques en secteurs	pie	Visualisation de données proportionnelles
Graphes Git	gitGraph	Stratégies de branches

Exemples réels :

• Diagrammes de séquence pour les flux Frontend → API Gateway → Payment Service API

• Diagrammes de Gantt pour votre feuille de route produit du T2 2026 avec dépendances

• Diagrammes d’état pour le cycle de vie d’une commande : En attente → Payé → Expédié → Livré

Les organigrammes, diagrammes de séquence, diagrammes ER et diagrammes d’état sont les plus courants pour les équipes de développement. Les équipes produit et opérations s’orientent généralement vers les parcours utilisateurs, diagrammes de Gantt et graphiques en secteurs pour les processus métier.

sequenceDiagram
    participant User
    participant API
    User->>API: POST /login
    API-->>User: 200 OK + Token

Comment créer des diagrammes Mermaid

Pour créer rapidement des organigrammes, il faut d’abord comprendre la structure de base. Vous pouvez créer des diagrammes avec n’importe quel éditeur de texte en utilisant la syntaxe Mermaid.

Procédure étape par étape :

1. Commencez par un mot-clé de diagramme (graph TD, sequenceDiagram, gantt)

2. Définissez des nœuds ou participants avec des identifiants et des étiquettes

3. Reliez les éléments avec des flèches ou des liaisons

4. Ajoutez des étiquettes et des regroupements au besoin

Voici un organigramme fonctionnel de processus de connexion :

graph TD
    U[User] --> LP[Login Page]
    LP --> AS[Auth Service]
    AS --> DB[(User Database)]
    AS -->|Success| DASH[Dashboard]
    AS -->|Failure| ERR[Error Page]

Types de flèches et étiquettes :

• –> crée une flèche dirigée standard

• –>|label| ajoute du texte conditionnel sur les liens

• — trace une ligne sans pointe de flèche

• -.-> produit une flèche en pointillés pour les relations indirectes

Mermaid dispose automatiquement les nœuds à l’aide des algorithmes d’agencement ELK. Concentrez-vous sur la structure logique et la dénomination plutôt que sur le positionnement manuel : aucun code supplémentaire n’est nécessaire pour l’emplacement.

Où utiliser les diagrammes Mermaid en 2026

De nombreuses plateformes grand public prennent désormais en charge Mermaid nativement ou via des extensions, ce qui permet de démarrer immédiatement.

Environnements clés :

• GitHub et GitLab : Rendu natif dans les fichiers README.md, la documentation, les issues et les wikis

• Générateurs de sites statiques : Docusaurus, MkDocs et Sphinx avec des extensions

• Portails développeurs internes : Backstage et applications React personnalisées

• Outils de prise de notes : Notion et Obsidian avec support intégré des graphiques Mermaid

Visual Studio Code et les IDE JetBrains proposent la prévisualisation en direct via des extensions, vous permettant de visualiser vos diagrammes en temps réel. Cela aide à détecter une erreur de syntaxe avant de valider les modifications.

Certaines plateformes comme Confluence Cloud nécessitent des modules complémentaires. Les équipes stockent souvent les diagrammes dans des dépôts de code tout en conservant les images exportées à côté pour une plus grande visibilité.

Rendu des diagrammes Mermaid sur différentes plateformes

Le rendu transforme le texte Mermaid en visuels SVG/HTML. La méthode dépend de l’intégration de Mermaid avec votre plateforme hôte.

Le modèle général : placez le code Mermaid dans des blocs de code délimités avec l’identifiant de langage mermaid. GitHub, GitLab et les générateurs de documentation affichent automatiquement ces blocs lorsqu’ils sont consultés dans un navigateur.

Pour le développement local, des extensions ou des plugins offrent un aperçu en direct. Dans la documentation Sphinx, activez le rendu via des extensions comme sphinxcontrib-mermaid qui traitent les diagrammes générés lors du build.

Rendu de Mermaid dans les fichiers Markdown

Pour afficher du Mermaid en Markdown :

1. Utilisez trois backticks pour ouvrir un bloc de code

2. Spécifiez mermaid comme identifiant de langage

3. Ajoutez votre définition de diagramme à l’intérieur

4. Fermez avec trois backticks

```mermaid
flowchart LR
    A[Step 1] -->|Process| B[Step 2]
    B -->|Complete| C[Step 3]
```

• GitHub, GitLab et les sites de documentation modernes gèrent directement cette syntaxe

• Testez le rendu dans un environnement d’aperçu avant de fusionner en production

• Le thème par défaut des graphiques Mermaid convient à la plupart des documentations

Rendu de Mermaid dans Obsidian

Obsidian affiche Mermaid à partir d’un bloc de code mermaid délimité en mode Lecture et en Aperçu en direct. La prise en charge de Mermaid est intégrée, vous n’avez donc pas besoin de plugin communautaire pour un diagramme de base.

Si un diagramme ne s’affiche pas :

1. Vérifiez que la balise d’ouverture soit exactement ```mermaid.
2. Assurez-vous que la première ligne contienne un mot-clé valide comme flowchart LR.
3. Remplacez les étiquettes contenant de la ponctuation par des guillemets, par exemple A["Review: blocked?"].
4. Réduisez l’exemple à deux nœuds, puis réintégrez les lignes progressivement.
5. Vérifiez si votre version d’Obsidian prend en charge la syntaxe Mermaid plus récente que vous avez copiée.

Pour d’autres extensions Markdown spécifiques à Obsidian, consultez le guide de formatage de texte pour Obsidian.

Rendu de Mermaid dans les IDE et outils locaux

Le plugin Visual Studio Code pour Mermaid permet un aperçu en direct côte à côte lors de l’édition. Plusieurs extensions proposent la coloration syntaxique et des suggestions de réparation de diagrammes complexes.

Les IDE JetBrains offrent des fonctionnalités similaires via des plugins, avec souvent des détections d’erreurs et options d’export. Un bouton de réparation automatique de diagramme peut corriger les erreurs de syntaxe courantes.

Les aperçus locaux permettent de corriger les erreurs avant d’effectuer un push vers vos dépôts Git. Standardisez un jeu d’extensions recommandé dans votre documentation développeur.

Exportation et partage des diagrammes Mermaid

Bien que les options d’édition basées sur le code conviennent parfaitement aux développeurs, les parties prenantes préfèrent souvent des images statiques pour les présentations Microsoft PowerPoint et les rapports.

Formats d’exportation courants :

• PNG : Partage rapide via les outils de messagerie

• SVG : Graphiques vectoriels haute définition pour les diapositives

• PDF : Documents imprimables

Les flux de travail d’exportation varient selon l’outil. Certains intègrent un bouton d’exportation, tandis que d’autres nécessitent l’éditeur Mermaid Chart ou des outils en ligne comme Mermaid Live Editor. Des outils en ligne de commande permettent de générer des images par lots à partir de plusieurs fichiers de diagrammes dans le cadre de la CI/CD.

Conservez toujours la source Mermaid originale à côté des fichiers exportés afin que vos diagrammes restent éditables.

Convertir des diagrammes Mermaid en formats d’image

Mini-procédure avec un éditeur en ligne :

1. Ouvrez Mermaid Live Editor dans votre navigateur

2. Collez votre code Mermaid ou utilisez des modèles de diagrammes

3. Ajustez les paramètres de style de votre graphique Mermaid

4. Configurez plusieurs thèmes si nécessaire (options sombre et clair disponibles)

5. Cliquez sur « Télécharger SVG » ou « Télécharger PNG »

Veillez à ce que les diagrammes exportés utilisent des polices et couleurs conformes à votre charte graphique. Les captures d’écran de GitHub risquent d’être pixellisées : privilégiez l’exportation au format SVG pour vos présentations.

Bonnes pratiques et limites des diagrammes Mermaid

Mermaid est un outil puissant qui donne ses meilleurs résultats lorsqu’il est utilisé avec un périmètre et une structure bien réfléchis.

Recommandations :

• Limitez chaque diagramme à un seul concept clair

• Utilisez des étiquettes de nœuds explicites et des conventions de nommage cohérentes

• Regroupez les étapes liées grâce aux blocs de sous-graphes (subgraph)

• Conservez les diagrammes complexes dans des fichiers séparés plutôt que dans un seul document massif

Limites à prendre en compte :

• Les systèmes vastes et denses deviennent difficiles à gérer sous forme de code

• Le contrôle de la mise en page est approximatif (pas de positionnement au pixel près)

• Le style est moins flexible qu’avec des outils de dessin traditionnels ou un tableau blanc virtuel

• Moins adapté aux maquettes d’interface utilisateur ou au dessin purement artistique

Utilisez Mermaid pour les aperçus d’architecture et les workflows. Passez à des outils spécialisés lorsque des mises en page au pixel près ou des topologies réseau complexes sont requises. Un éditeur visuel de diagrammes reste utile dans certains cas.

Démarrer rapidement avec les diagrammes Mermaid

Plan d’action pour les nouveaux utilisateurs :

1. Choisissez un type de diagramme (généralement un organigramme pour représenter des processus simples)

2. Installez une extension avec éditeur visuel ou assistant IA, ou ouvrez Mermaid Live Editor

3. Modélisez un processus réel de votre projet actuel — votre pipeline de déploiement 2026 est un excellent exemple

4. Faites évoluer votre diagramme au fur et à mesure que vous apprenez la syntaxe

Ressources clés :

• Documentation officielle de Mermaid pour la référence complète de la syntaxe

• Mermaid Live Editor pour expérimenter avec les fonctionnalités de génération IA intégrées

• Extensions VS Code avec extraits de code et modèles

• Envisagez un compte de base sur des plateformes collaboratives pour les fonctionnalités d’équipe

Ajoutez une section « Directives relatives aux diagrammes » dans votre guide d’ingénierie couvrant les conventions de nommage, les types de diagrammes privilégiés et les autorisations. Certaines équipes constatent que la description en langage naturel combinée aux outils de chat IA intégrés accélère la création de diagrammes, quel que soit le niveau technique.

L’adoption des diagrammes Mermaid aligne votre documentation sur les mêmes pratiques de révision et d’automatisation que celles utilisées pour le code source. Que vous soyez ingénieur en machine learning documentant des pipelines de modèles ou responsable de projet modélisant des flux de travail, Mermaid apporte des visuels sous contrôle de version à toute votre équipe. Lancez-vous dès aujourd’hui avec un premier diagramme.