Diagrammes Mermaid en Markdown : organigrammes, séquences et plus

Les diagrammes expliquent les processus, les architectures et les plannings mieux que des paragraphes de texte. Mais les dessiner dans un logiciel graphique implique d’exporter des images, de les stocker à côté de la doc et de tout redessiner au moindre changement.

Mermaid règle ce problème : vous décrivez le diagramme en quelques lignes de texte dans votre fichier Markdown, et l’outil d’aperçu le dessine. Le diagramme vit dans le même fichier, apparaît dans les diffs et se met à jour aussi facilement qu’une phrase. GitHub, GitLab, Obsidian, de nombreux générateurs de documentation et Markdown Preview Editor affichent Mermaid nativement.

Comment ajouter un diagramme Mermaid

Créez un bloc de code délimité et indiquez mermaid comme langage :

markdown```mermaid
flowchart LR
  A[Écrire] --> B[Aperçu]
  B --> C{Prêt ?}
  C -- oui --> D[Exporter]
  C -- non --> A
```

L’outil d’aperçu le transforme en :

La première ligne indique le type de diagramme. Tout ce qui suit décrit les nœuds et les liaisons.

Organigrammes

Les organigrammes (flowcharts) sont le type de diagramme le plus utilisé. La direction suit le mot-clé : TD ou TB (de haut en bas), BT, LR (de gauche à droite) ou RL.

mermaidflowchart TD
  start([Début]) --> input[/Lire le fichier/]
  input --> valid{Est-il valide ?}
  valid -- Oui --> save[(Enregistrer en base)]
  valid -- Non --> error[Afficher une erreur]
  error --> input

Les délimiteurs autour d’un libellé définissent la forme du nœud :

Liaisons : --> est une flèche, --- une ligne sans flèche, -.-> une flèche en pointillés et ==> une flèche épaisse. Ajoutez un libellé avec -- text --> ou -->|text|.

Regroupez les nœuds liés avec subgraph :

mermaidflowchart LR
  subgraph Navigateur
    editor[Éditeur] --> preview[Aperçu]
  end
  preview --> export[HTML / PDF]

Diagrammes de séquence

Les diagrammes de séquence montrent comment des participants échangent des messages au fil du temps — idéal pour les API, les flux d’authentification et les parcours utilisateur.

mermaidsequenceDiagram
  participant U as Utilisateur
  participant A as Application
  participant S as Serveur
  U->>A: Clic sur « Se connecter »
  A->>S: POST /login
  S-->>A: 200 OK + jeton
  A-->>U: Affiche le tableau de bord
  Note over A,S: Le jeton expire au bout d’une heure

->> est une flèche pleine (une requête), -->> une flèche en tirets (une réponse). Note over, Note left of et Note right of ajoutent des commentaires. Utilisez les blocs loop, alt/else et opt pour représenter répétitions et embranchements.

Diagrammes de Gantt

Un diagramme de Gantt transforme une liste de tâches en planning. Une tâche peut commencer à une date donnée ou after (après) une autre tâche.

mermaidgantt
  title Sprint de documentation
  dateFormat YYYY-MM-DD
  section Rédaction
  Plan              :done,   a1, 2026-10-01, 2d
  Premier jet       :active, a2, after a1, 4d
  section Relecture
  Relecture croisée :        a3, after a2, 3d
  Publication       :milestone, after a3, 0d

Diagrammes d’états

Les diagrammes d’états décrivent comment un élément passe d’un état à un autre — une commande, un document, un composant d’interface.

mermaidstateDiagram-v2
  [*] --> Brouillon
  Brouillon --> Relecture : soumettre
  Relecture --> Brouillon : modifications demandées
  Relecture --> Publication : approuver
  Publication --> [*]

Camemberts

Pour visualiser rapidement une répartition, un camembert (pie chart) prend une ligne par part :

mermaidpie title Où passe le temps consacré à la documentation
  "Rédaction" : 45
  "Mise en forme" : 15
  "Mise à jour des diagrammes" : 40

Mermaid prend aussi en charge les diagrammes de classes, les diagrammes entité-association, les cartes mentales, les frises chronologiques, les graphes Git, les matrices à quadrants et plus encore. La syntaxe de chacun est documentée sur le site officiel de Mermaid.

Conseils pour des diagrammes lisibles

• Restez concis. Au-delà de 15 à 20 nœuds, un diagramme devient difficile à lire. Découpez-le en plusieurs diagrammes, un par idée.
• Choisissez la direction à dessein. LR convient aux processus de quelques étapes ; TD aux hiérarchies et aux longs flux, surtout sur écran étroit.
• Utilisez des identifiants courts et des libellés lisibles. Écrivez auth[Check the session] plutôt que d’utiliser le libellé comme identifiant : les liaisons restent courtes.
• Mettez entre guillemets les libellés contenant des caractères spéciaux : A["Price: $5 (incl. tax)"].
• Ajoutez des commentaires avec %% en début de ligne. Ils sont ignorés au rendu.
• Prévisualisez pendant la frappe. Une flèche ou un crochet manquant casse tout le diagramme : un aperçu en direct évite bien des tâtonnements. Dans Markdown Preview Editor, le diagramme est redessiné à chaque modification, et le bouton Diagramme Mermaid de la barre Éditeur avancé insère un modèle de départ.

Partager des documents avec des diagrammes

Lorsque vous exportez un document en HTML ou en PDF, les diagrammes sont inclus sous forme d’images : le lecteur n’a pas besoin d’installer Mermaid. Pour ajouter des formules à côté de vos diagrammes, consultez comment écrire des formules en Markdown, et pour tout le reste — tableaux, listes de tâches, encadrés — gardez l’aide-mémoire Markdown sous la main.