La création de diagrammes a toujours été l'une de mes tâches les moins appréciées dans la documentation. Je passais des heures à déplacer des boîtes et je me retrouvais toujours avec quelque chose qui semblait amateur. Cela a changé lorsque j'ai découvert Mermaid. Dans cet article, je partage comment j'utilise Mermaid CLI pour créer des diagrammes en utilisant uniquement du texte, et comment les outils d'intelligence artificielle ont complètement transformé et rationalisé ce processus.

Qu'est-ce que Mermaid ?

Mermaid est un outil gratuit et open source qui transforme du texte en diagrammes, un peu comme Markdown transforme du texte en contenu formaté. Il est entièrement gratuit sous licence MIT, vous pouvez donc l'utiliser pour le travail ou des projets personnels sans vous soucier des coûts de licence. Il peut être utilisé pour créer toutes sortes de diagrammes, tels que :

Organigrammes
Diagrammes de séquence
Diagrammes de classes
Diagrammes entité-relation
Diagrammes de Gantt
Diagrammes circulaires
Cartes de parcours utilisateur
Graphes Git
Diagrammes d'états
Et bien d'autres

Ce que j'aime le plus, c'est que je n'ai plus jamais à faire glisser de boîtes. J'écris simplement du texte, et Mermaid crée le diagramme. Après des années à me battre avec les outils de diagrammes traditionnels, cette approche me semble une révélation.

Démarrer avec Mermaid CLI

J'ai commencé à utiliser Mermaid dans le navigateur, mais la version CLI (Command Line Interface) est là où la vraie magie opère. Elle vous permet de transformer vos diagrammes textuels en fichiers image réels que vous pouvez insérer dans des documents, des présentations ou n'importe où ailleurs. Et c'est super facile à utiliser.

La syntaxe de base pour utiliser Mermaid CLI est :

npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png

Cette commande :

npx @mermaid-js/mermaid-cli : Exécute l'outil Mermaid CLI sans nécessiter d'installation globale
-i diagram.mmd : Spécifie le fichier d'entrée contenant votre définition de diagramme Mermaid
-o diagram.png : Définit le nom du fichier de sortie et le format (PNG dans ce cas)

Vous pouvez également générer des fichiers SVG qui sont évolutifs et parfaits pour une utilisation sur le web :

npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

Vous pouvez également prévisualiser rapidement votre code Mermaid en ligne à l'aide d'outils comme MermaidChart, ce qui est idéal pour tester et partager des diagrammes sans rien installer.

Créer votre premier diagramme Mermaid

Commençons par un organigramme simple. Créez un fichier nommé flowchart.mmd avec ce contenu :

flowchart TD
A[Démarrer] --> B{Décision}
B -->|Oui| C[Processus 1]
B -->|Non| D[Processus 2]
C --> E[Fin]
D --> E

Maintenant, générez une image PNG de ce diagramme :

npx @mermaid-js/mermaid-cli -i flowchart.mmd -o flowchart.png

Cela créera un organigramme propre et professionnel montrant un processus de décision simple, comme ceci :

Organigramme simple montrant un processus de décision

Vous pouvez utiliser cette même approche pour tout type de diagramme pris en charge par Mermaid.

Par exemple, si vous avez besoin de visualiser une architecture système (comme je l'ai fait récemment), vous pourriez créer quelque chose comme ceci :

flowchart TD
Client([Navigateur Web]) --HTTP/HTTPS--> LB[Équilibreur de charge]
LB --> API1[Serveur API 1]
LB --> API2[Serveur API 2]
API1 --> DB[(Base de données)]
API2 --> DB
API1 --> Cache[(Cache Redis)]
API2 --> Cache

Ce qui produit ce diagramme :

Diagramme d'architecture montrant des serveurs web, un équilibreur de charge et une base de données

Comment l'IA suralimente la création de diagrammes

C'est là que l'intelligence artificielle devient un atout majeur. Au lieu d'écrire manuellement des diagrammes Mermaid, des outils d'IA comme Cursor et Windsurf peuvent analyser des descriptions textuelles et générer automatiquement des définitions de diagrammes pour vous.

J'ai récemment dû créer un diagramme d'architecture pour un projet AWS + Drupal avec une architecture complexe. Sans IA, cela aurait pris beaucoup de temps pour cartographier tous les composants et leurs connexions. Au lieu de cela, j'ai transmis les spécifications du projet à l'assistant IA de Cursor, lui ai demandé d'extraire les composants du système et leurs relations, et j'ai obtenu du code Mermaid qui m'a aidé à créer le diagramme plus efficacement.

Utiliser l'IA de Cursor pour générer des diagrammes

Cursor est un IDE doté d'une IA puissante qui comprend à la fois le code et le langage naturel. Sa capacité à interpréter des descriptions techniques et à les convertir en syntaxe Mermaid structurée est remarquable. Voici mon flux de travail typique :

Copiez le texte pertinent qui décrit le concept que vous souhaitez visualiser
Utilisez une invite telle que : « Générez un diagramme Mermaid basé sur cette description »
Cursor analysera le texte et générera la syntaxe Mermaid appropriée
Enregistrez le code Mermaid généré dans un fichier .mmd
Utilisez Mermaid CLI pour le convertir en image

Par exemple, vous pourriez inviter Cursor avec des instructions telles que :

« Créez un organigramme Mermaid montrant un processus d'inscription utilisateur »
« Générez un diagramme de séquence Mermaid pour ce flux de requêtes API »
« Convertissez cette chronologie de projet en un diagramme de Gantt Mermaid »
« Créez un diagramme de classes Mermaid à partir de cette description de modèle de domaine »

En quelques secondes, vous obtiendrez un diagramme Mermaid complet qui représente fidèlement votre concept.

Aller plus loin avec l'IA de Windsurf

Windsurf (de Codeium) exploite l'IA pour pousser l'automatisation des diagrammes encore plus loin. Ses modèles d'IA peuvent analyser des bases de code entières ou des ensembles de documentation pour créer des scripts qui :

Scannent les fichiers texte à la recherche de descriptions qui pourraient être visualisées
Extraient les éléments clés et les relations
Génèrent la syntaxe Mermaid appropriée en fonction du type de contenu
Exécutent automatiquement Mermaid CLI pour créer des images de diagrammes
Intègrent ces diagrammes dans vos documents

Cela crée un flux de documentation continu où vos diagrammes restent synchronisés avec votre contenu écrit. L'IA peut détecter lorsque votre code ou votre documentation change suffisamment pour justifier des mises à jour de diagrammes, rendant l'ensemble du processus quasi automatique.

Types de diagrammes avancés

Mermaid prend en charge de nombreux types de diagrammes au-delà des simples organigrammes. Voici quelques-uns des plus utiles pour la documentation d'architecture :

Diagrammes de séquence

Parfaits pour illustrer comment les composants interagissent au fil du temps :

sequenceDiagram
participant Utilisateur
participant API
participant BaseDeDonnees

Utilisateur->>API: GET /produits
API->>BaseDeDonnees: Requête produits
BaseDeDonnees-->>API: Retourne les résultats
API-->>Utilisateur: Réponse JSON

Ce qui produit ce diagramme de séquence :

Diagramme de séquence montrant le flux de requêtes API entre Utilisateur, API et Base de données

Diagrammes de classes

Idéaux pour montrer la conception orientée objet :

classDiagram
class Commande {
    +String id
    +Date createdAt
    +OrderStatus status
    +calculerTotal()
}
class Client {
    +String id
    +String nom
    +String email
    +passerCommande()
}
Client "1" -- "plusieurs" Commande: passe

Ce qui produit ce diagramme de classes :

Diagramme de classes montrant les classes Client et Commande avec leur relation

Diagrammes Entité-Relation

Géniaux pour la conception de bases de données :

erDiagram
CLIENT ||--o{ COMMANDE : passe
COMMANDE ||--|{ LIGNE_COMMANDE : contient
CLIENT }|..|{ ADRESSE_LIVRAISON : utilise

Ce qui produit ce diagramme entité-relation :

Diagramme Entité-Relation montrant les relations client, commande, ligne de commande et adresse de livraison

Exemples pratiques

Mermaid CLI peut être utilisé pour divers besoins de visualisation, y compris la documentation d'architecture système (comme mentionné précédemment), mais aussi pour :

Planification de projet

Pour la planification de projet, vous pouvez créer un diagramme de Gantt montrant les phases et les dépendances :

gantt
titre Chronologie du projet
dateFormat  YYYY-MM-DD
section Recherche
Collecte des exigences :a1, 2025-01-01, 10j
Étude de marché       :après a1, 7j
section Développement
Développement frontend  :b1, 2025-01-18, 14j
Développement backend   :b2, 2025-01-18, 21j
section Tests
Tests d'intégration   :c1, après b1 b2, 7j
Acceptation utilisateur :c2, après c1, 7j

Ce qui produit cette visualisation de chronologie :

Diagramme de Gantt montrant la chronologie du projet avec les phases de développement

Documentation de processus

Pour documenter les processus métier, Mermaid peut créer des organigrammes clairs :

flowchart TD
Début([Commande client]) --> A{Stock disponible ?}
A -->|Oui| B[Traiter le paiement]
A -->|Non| C[Processus de mise en attente]
B --> D[Expédier le produit]
C --> E[Notifier le client]
D & E --> Fin([Commande terminée])

Ce qui produit cet organigramme de processus :

Organigramme de processus montrant un flux de travail de commande client

Possibilités futures avec l'IA et l'automatisation

La combinaison de Mermaid CLI et des outils d'IA ouvre des possibilités passionnantes pour l'automatisation de la documentation. J'imagine un système qui pourrait :

Surveiller les fichiers de documentation pour les changements
Utiliser l'IA pour identifier le contenu qui pourrait bénéficier d'une visualisation
Générer la syntaxe Mermaid appropriée en fonction du contenu
Exécuter automatiquement Mermaid CLI pour créer de nouvelles images de diagrammes
Intégrer intelligemment les diagrammes dans la documentation avec le contexte approprié

Un tel système permettrait de maintenir les diagrammes synchronisés avec la documentation sans intervention manuelle. Bien que je n'aie pas encore construit ce système, les outils d'IA actuels et Mermaid CLI le rendent entièrement possible.

Conseils pour de meilleurs diagrammes

Utilisez des formes significatives : Mermaid offre diverses formes de nœuds pour distinguer différents types de composants (bases de données, services, systèmes externes)
Ajoutez de la couleur pour plus de clarté : Utilisez des couleurs pour regrouper les composants connexes ou mettre en évidence les éléments importants
Restez simple : Évitez de surcharger les diagrammes ; créez plusieurs diagrammes ciblés plutôt qu'un seul diagramme complexe
Utilisez des sous-graphes : Regroupez les composants connexes à l'aide de sous-graphes pour montrer les limites logiques
Ajoutez des titres et des descriptions : Rendez vos diagrammes autonomes avec des titres clairs et des descriptions concises

En résumé

Mermaid offre une approche pratique de la création de diagrammes qui s'intègre bien aux flux de travail de développement. La nature textuelle des diagrammes Mermaid les rend compatibles avec le contrôle de version et plus faciles à maintenir que les formats de diagrammes traditionnels.

Lorsqu'ils sont combinés avec des outils d'IA, le processus devient encore plus efficace. Ces outils peuvent aider à générer du code de diagramme à partir de descriptions, le rendant accessible même à ceux qui n'ont pas de connaissances techniques approfondies.

Voici quelques réflexions finales sur l'utilisation de Mermaid :

Courbe d'apprentissage : La syntaxe est relativement simple à apprendre, surtout si vous êtes déjà familier avec Markdown ou d'autres formats textuels.
Intégration : Les diagrammes Mermaid fonctionnent sur de nombreuses plateformes, notamment GitHub, Notion et d'autres systèmes de documentation.
Coût : En tant qu'outil open source sous licence MIT, Mermaid est gratuit à utiliser à toutes fins.
Efficacité : La création de diagrammes basée sur du texte peut être plus rapide que la création de diagrammes traditionnelle une fois que vous maîtrisez la syntaxe.
Facilité d'installation : L'utilisation de npx pour exécuter Mermaid CLI élimine les problèmes d'installation.

Si vous cherchez à améliorer votre processus de documentation, envisagez d'essayer Mermaid pour votre prochain projet. La capacité de créer des diagrammes professionnels directement à partir de descriptions textuelles, avec l'aide potentielle d'outils d'IA, pourrait transformer votre approche de la visualisation dans votre travail.

Automation

Automatisation de la création de diagrammes avec Mermaid CLI et des outils d'IA