Mermaid ou canevas de diagramme : quand le diagram as code fonctionne, et quand ce n'est pas le cas

Dans les équipes techniques, peu de débats d'outillage durent aussi longtemps que celui-ci. Certains veulent chaque diagramme sous forme de code, en Mermaid, relu dans les pull requests. D'autres veulent un canevas où déplacer des boîtes et voir le système. Les deux camps ont raison, mais pas sur les mêmes diagrammes.

Ce guide compare honnêtement Mermaid et un canevas de diagramme : ce que chacun fait bien, là où chacun atteint ses limites, un tableau de décision pour les cas courants, et le même petit système dessiné des deux façons.

Ce que Mermaid fait bien

Mermaid transforme quelques lignes de texte en diagramme. Les avantages sont réels :

• Il vit à côté du code. Un diagramme dans un fichier Markdown évolue dans la même pull request que le code qu'il décrit, et les relecteurs voient le diff.
• Il s'affiche là où les développeurs travaillent déjà. GitHub et GitLab rendent les blocs de code Mermaid dans les fichiers Markdown, les issues et les pull requests, et des outils comme Notion et Obsidian les affichent aussi.
• Ni outil ni compte supplémentaire. Toute personne qui peut modifier le fichier peut modifier le diagramme.
• Les diagrammes de séquence sont excellents. Pour un flux de requêtes entre quatre services, la syntaxe de séquence de Mermaid est difficile à battre.
• Les assistants IA l'écrivent couramment. Demandez un logigramme Mermaid à n'importe quel assistant conversationnel : la plupart du temps, la syntaxe obtenue est valide.

Les limites de Mermaid

• Vous ne maîtrisez pas la mise en page. Mermaid place les nœuds automatiquement. Ajoutez un seul lien et tout le dessin peut se réorganiser ; au-delà de quelques dizaines de nœuds, il devient difficile à lire.
• Les diffs texte masquent les changements visuels. Une modification d'une ligne dans une pull request peut déplacer la moitié du diagramme, et les relecteurs ne voient que la ligne.
• Le vocabulaire est pauvre pour l'infrastructure. Les formes de logigramme sont génériques. Des types de diagrammes plus récents existent pour l'architecture et C4, mais ils sont moins aboutis que les logigrammes et les diagrammes de séquence.
• Les non-développeurs le modifient rarement. Les product managers, les designers et les équipes support peuvent lire le résultat, mais ne touchent généralement pas à la source.
• Pas de session partagée en direct. Vous modifiez du texte dans votre éditeur ; pas de curseurs, pas de revue en direct, personne pour voir une modification arriver.

Ce qu'un canevas fait bien

• La mise en page vous appartient. La position porte du sens : le tracé d'une frontière de confiance, le parcours d'une requête de gauche à droite, le cluster au centre.
• Des nœuds typés et des cadres. Sur un canevas comme Archboard, un Service Kubernetes ou un conteneur C4 est un nœud avec ports, et les namespaces ou les VPC sont des cadres qui contiennent leurs éléments.
• Tout le monde peut modifier. Les personnes qui n'ouvrent jamais le dépôt peuvent quand même corriger une étiquette ou ajouter une note.
• Collaboration et partage en direct. Plusieurs personnes, et des agents IA, modifient ensemble avec leurs curseurs, et un lien en direct ou une intégration garde chaque lecteur sur la version actuelle.

Les limites d'un canevas

• Il s'éloigne du code si sa mise à jour ne fait pas partie de votre workflow. Par défaut, un canevas n'est pas dans la pull request.
• Certains formats sont opaques. Un PNG ou un fichier propriétaire ne se prête ni au diff ni à la génération. Archboard atténue ce problème avec l'export JSON et un JSON Schema publié, mais un document JSON n'est toujours pas un bloc Markdown de dix lignes.
• Il faut un outil. Les lecteurs peuvent consulter un lien de partage sans compte, mais les éditeurs ont besoin d'un compte.

Un tableau de décision

La logique : Mermaid l'emporte quand le diagramme appartient à un changement et vit dans le code. Un canevas l'emporte quand le diagramme appartient à l'équipe et survit à chaque changement pris isolément.

Le même système, des deux façons

Voici un petit système en Mermaid :

flowchart LR
  user([Customer]) -->|HTTPS| web
  subgraph shop [Online shop]
    web[Web app] -->|JSON| api[Orders API]
    api -->|SQL| db[(Orders DB)]
    api -->|OrderPlaced| q[[order-events]]
    q --> worker[Email worker]
  end
  worker -->|SMTP| mail[Email provider]

Il est lisible, ses diffs restent propres et GitHub l'affiche. Voici maintenant le même logigramme sur un canevas. Nous l'avons confié à un agent IA connecté à Archboard via MCP, avec une correspondance entre identifiants Mermaid et types de nœuds : user vers une personne C4, web, api et worker vers des conteneurs C4, db vers Postgres, q vers un Sujet (topic), mail vers un système externe. L'agent l'a dessiné en une étape, puis une seconde étape l'a disposé sur deux rangées :

Le subgraph est devenu un cadre, les nœuds sont devenus des nœuds typés avec ports, et le résultat est un point de départ que vous pouvez maintenant organiser, annoter et partager comme n'importe quel autre diagramme.

Utiliser les deux, en connaissance de cause

Une répartition qui fonctionne pour la plupart des équipes :

1. Mermaid pour les diagrammes qui appartiennent à un changement : diagrammes de séquence dans les documents de conception et les pull requests, machines à états à côté du code, petits logigrammes dans les README.
2. Un canevas pour les diagrammes qui appartiennent à l'équipe : vues d'ensemble du système, infrastructure, revues de sécurité, onboarding.
3. Faites le lien entre les deux. Partez de Mermaid si vous l'avez déjà : un agent connecté à Archboard via MCP peut transformer un logigramme Mermaid en diagramme sur canevas avec de vrais types de nœuds. Exportez le canevas en JSON dans le dépôt quand vous voulez qu'il soit relu avec le code, et liez le diagramme en direct depuis le README.

FAQ

Puis-je coller du Mermaid dans l'éditeur Archboard ? Pas directement pour l'instant. Un agent IA connecté via MCP peut dessiner un logigramme Mermaid, subgraphs compris, sous forme de diagramme sur canevas avec de vrais types de nœuds. Les autres types de diagrammes Mermaid, comme les diagrammes de séquence, ne sont pas convertis.

Un diagramme sur canevas apparaît-il dans les pull requests ? Pas de lui-même. Exportez-le en JSON ou en SVG dans le dépôt si vous voulez qu'il soit relu avec le code, ou liez le diagramme en direct depuis la pull request.

Le diagram as code est-il toujours plus à jour ? Seulement si quelqu'un le met à jour. Un bloc Mermaid que personne ne touche se périme aussi vite qu'un canevas ; la différence, c'est qu'il se trouve plus près du changement qui devrait le mettre à jour.

Et PlantUML ou Structurizr ? Mêmes compromis. PlantUML est solide pour l'UML et les diagrammes de séquence ; Structurizr est conçu pour décrire des modèles C4 sous forme de code. Choisissez selon qui modifie le diagramme et combien de temps il doit vivre.

Lequel les assistants IA gèrent-ils le mieux ? Les deux. Les assistants écrivent couramment du Mermaid, et via MCP un agent peut aussi modifier directement un canevas, où chacun voit le changement en direct et peut l'annuler.

Commencez gratuitement — un siège, sans carte bancaire.