Mermaid : écrire ses logigrammes en code

Ce qu’est Mermaid

Mermaid est une bibliothèque JavaScript, publiée pour la première fois en 2014, qui transforme une description textuelle en diagramme. Elle gère les logigrammes, les diagrammes de séquence, d’états, les diagrammes de Gantt et d’autres. Un logigramme minimal ressemble à ceci :

flowchart TD
  A([Commande reçue]) --> B[Vérifier le stock]
  B --> C{En stock ?}
  C -->|Oui| D[Expédier la commande]
  C -->|Non| E[Prévenir le client]

Le moteur de rendu s’occupe des formes, des positions et des flèches. Vous ne décrivez que la structure.

Pourquoi écrire ses diagrammes en code

• Versionnement : le diagramme est du texte, ses modifications apparaissent dans les diffs et les revues de code.
• Pas de fichiers binaires : rien à réexporter quand le processus change, on modifie une ligne.
• Il vit avec la documentation : dans un README, une page de wiki ou une note d’architecture.
• Il s’affiche là où les équipes travaillent déjà, sans extension sur de nombreuses plateformes.

La contrepartie est le contrôle : la mise en page est automatique, on ne place pas une case exactement où l’on veut. Pour la plupart des documentations, c’est un avantage plutôt qu’une limite.

Où Mermaid s’affiche

GitHub et GitLab affichent les blocs de code Mermaid dans les fichiers Markdown, les issues et les pull ou merge requests ; voir Mermaid sur GitHub et GitLab. Notion et Obsidian le prennent aussi en charge nativement, et de nombreux générateurs de documentation proposent des extensions ; voir Mermaid dans Notion, Obsidian et les outils de documentation.

Mermaid ou logiciel de dessin ?

Les logiciels de dessin et les tableaux blancs conviennent mieux aux croquis libres, aux affiches d’architecture et à tout ce où la position a un sens. Mermaid convient mieux aux schémas qui suivent une structure (étapes, décisions, responsables), que plusieurs personnes maintiennent et qui doivent rester alignés avec un texte. Règle pratique : si le schéma sera mis à jour plus d’une fois et que sa mise en page n’a pas besoin d’être parfaite au pixel près, écrivez-le en code.

Apprendre la syntaxe

Les logigrammes n’ont besoin que de quelques éléments : une direction, des nœuds avec leur forme, des flèches avec une étiquette éventuelle. L’aide-mémoire de la syntaxe Mermaid les présente, et sous-graphes et styles explique comment regrouper les étapes par responsable et mettre en avant certaines parties.

D’une description au code Mermaid

Écrire du Mermaid à la main est rapide pour un petit schéma et fastidieux pour un grand. Autre solution : décrire le processus en langage courant, laisser un générateur de logigramme par IA construire le schéma, puis l’exporter en Mermaid. Flowchartio exporte un fichier flowchart TD dans lequel chaque responsable devient un sous-graphe, prêt à coller dans un README.

Mermaid ou image ?

Mermaid convient à la documentation qui évolue et qui vit dans des outils texte. Les présentations, les PDF et les e-mails ont encore besoin d’images. Le comparatif PNG, SVG ou Mermaid aide à choisir. Pour la documentation logicielle en général, y compris les intégrations d’API, voir logigrammes pour les API et les logiciels.