Comment utiliser l’IA pour créer des diagrammes Mermaid

L’IA permet de créer des diagrammes Mermaid à partir d’une description en langage naturel, sans maîtriser toute la syntaxe du langage. Ce guide explique comment utiliser ChatGPT, Claude, Gemini ou un outil spécialisé pour générer, vérifier, corriger et intégrer des diagrammes Mermaid dans une documentation, un projet logiciel ou une présentation.

Qu’est-ce qu’un diagramme Mermaid ?

Mermaid est un langage déclaratif qui transforme du texte en diagrammes. Au lieu de dessiner manuellement des formes et des flèches, il suffit de décrire les éléments, leurs relations et leur organisation.

Un diagramme Mermaid peut être affiché dans un navigateur ou dans un outil compatible, notamment sous forme de SVG. Il peut représenter :

• un organigramme ou une logique métier avec `flowchart` ;
• des échanges entre services avec `sequenceDiagram` ;
• une structure de classes avec `classDiagram` ;
• un modèle de données avec `erDiagram` ;
• une machine à états avec `stateDiagram-v2` ;
• une feuille de route avec `gantt` ou `timeline` ;
• un parcours utilisateur avec `journey` ;
• une hiérarchie avec `mindmap` ;
• un graphique simple avec `pie` ou `xychart-beta`.

L’IA ne « dessine » pas nécessairement le diagramme. Elle génère principalement le code Mermaid, qui doit ensuite être rendu par un outil compatible.

Exemple de syntaxe Mermaid

Quelques éléments courants peuvent être écrits directement dans une conversation ou une documentation :

• `flowchart TD` crée un organigramme orienté de haut en bas ;
• `flowchart LR` crée un organigramme de gauche à droite ;
• `A[Client] --> B[Serveur]` relie deux nœuds ;
• `sequenceDiagram` démarre un diagramme de séquence ;
• `Alice->>Bob: Bonjour` représente un message entre deux participants.

La syntaxe exacte dépend du type de diagramme et de la version de Mermaid utilisée.

Pourquoi utiliser l’IA pour créer des diagrammes Mermaid ?

Gagner du temps sur la syntaxe

La syntaxe Mermaid est relativement accessible, mais certaines constructions deviennent rapidement complexes : relations conditionnelles, sous-graphes, cardinalités, activations, classes ou styles.

Une IA peut convertir une description telle que « un client envoie une requête à une API, qui interroge une base de données avant de répondre » en une structure Mermaid exploitable.

Transformer une documentation en schéma

Un texte technique contient souvent assez d’informations pour générer un diagramme :

• étapes d’un processus ;
• composants d’une architecture ;
• acteurs d’un système ;
• relations entre tables ;
• enchaînement d’appels API ;
• transitions entre plusieurs états.

L’IA peut extraire ces informations et proposer une première représentation visuelle.

Faciliter les modifications

Un diagramme Mermaid est stocké sous forme de texte. Il est donc facile à modifier, versionner dans Git et intégrer à une documentation.

Une consigne comme « ajoute un service de cache entre l’API et la base de données » peut suffire à obtenir une nouvelle version du diagramme.

Conserver une documentation cohérente

Les diagrammes générés à partir d’un fichier texte peuvent être mis à jour en même temps que le code ou la documentation. Cette approche limite les images obsolètes qui ne correspondent plus à l’architecture réelle.

Quels outils utiliser pour générer des diagrammes Mermaid avec l’IA ?

ChatGPT, Claude ou Gemini

Les modèles conversationnels généralistes peuvent :

• générer du code Mermaid à partir d’une description ;
• choisir un type de diagramme ;
• expliquer une syntaxe ;
• corriger une erreur de rendu ;
• simplifier un diagramme trop chargé ;
• convertir un diagramme d’un type vers un autre.

Pour obtenir un résultat fiable, il est préférable de demander explicitement la syntaxe Mermaid et de préciser la version ou l’environnement de rendu.

Mermaid Live Editor

Mermaid Live Editor est un éditeur en ligne permettant de coller du code Mermaid et d’observer immédiatement le résultat. Il sert notamment à :

1. générer le code avec une IA ;
2. le coller dans l’éditeur ;
3. repérer les erreurs de syntaxe ;
4. ajuster la structure ;
5. exporter le diagramme selon les formats disponibles.

L’éditeur constitue une étape importante de validation, car une réponse apparemment correcte peut contenir une erreur empêchant l’affichage.

Mermaid Chart et les outils spécialisés

Mermaid Chart propose un environnement dédié à la création et à la gestion de diagrammes Mermaid, avec des fonctionnalités d’édition visuelle et, selon l’offre disponible, des fonctions assistées par IA.

Les services spécialisés peuvent être utiles lorsqu’un besoin porte sur :

• la collaboration en équipe ;
• l’export professionnel ;
• la gestion centralisée de nombreux diagrammes ;
• la conversion entre description et représentation visuelle.

Les fonctions, limites et tarifs évoluent régulièrement. Il est nécessaire de consulter les conditions actuelles de chaque service avant de choisir une solution.

GitHub, GitLab et les générateurs de documentation

GitHub et GitLab prennent en charge Mermaid dans certains contextes de Markdown et de documentation. Mermaid peut également être intégré dans des sites générés avec des outils comme Docusaurus, MkDocs, Astro ou d’autres systèmes disposant d’un plugin adapté.

La compatibilité dépend de la plateforme, de la version du moteur Mermaid et de la configuration du projet. Un diagramme qui fonctionne dans Mermaid Live Editor peut nécessiter une adaptation dans un autre environnement.

Comment créer un diagramme Mermaid avec une IA ?

Étape 1 : rassembler les informations

Avant d’interroger l’IA, identifier les éléments indispensables :

• les acteurs ou composants ;
• les actions effectuées ;
• l’ordre des opérations ;
• les conditions et exceptions ;
• les relations entre les éléments ;
• les informations qui doivent rester hors du diagramme.

Une description précise produit généralement un diagramme plus pertinent qu’une demande vague.

Par exemple, la phrase « crée un diagramme de mon application » manque de contexte. Une demande plus exploitable précise les composants, les échanges et le public visé.

Étape 2 : choisir le type de diagramme

Le format doit correspondre à l’objectif recherché.

| Besoin | Type Mermaid recommandé |

|---|---|

| Décrire un processus | `flowchart` |

| Montrer des appels entre services | `sequenceDiagram` |

| Représenter des tables et leurs relations | `erDiagram` |

| Décrire une architecture orientée objet | `classDiagram` |

| Montrer les états d’un objet | `stateDiagram-v2` |

| Planifier des tâches dans le temps | `gantt` |

| Illustrer un parcours utilisateur | `journey` |

| Représenter une hiérarchie | `mindmap` |

Si le type n’est pas évident, l’IA peut proposer plusieurs options. Il reste toutefois préférable de demander une recommandation argumentée plutôt que de lui laisser choisir sans contrainte.

Étape 3 : rédiger un prompt précis

Un bon prompt indique au minimum :

• le rôle attendu de l’IA ;
• le type de diagramme ;
• les données à représenter ;
• le sens de lecture ;
• le niveau de détail ;
• la compatibilité recherchée ;
• le format de réponse.

Exemple de prompt :

Tu es spécialiste de Mermaid et de la documentation technique. Crée un diagramme de séquence compatible avec Mermaid 10. Représente le parcours suivant : un utilisateur ouvre une application, l’application appelle une API, l’API vérifie un jeton auprès du service d’authentification, puis interroge une base de données. Affiche également le cas d’un jeton invalide. Utilise des noms courts, évite les fonctionnalités expérimentales et renvoie uniquement le code Mermaid sans explication.

Cette consigne limite les réponses trop longues et réduit le risque d’obtenir un format inutilisable.

Étape 4 : demander un code simple et compatible

La compatibilité est plus importante que la sophistication. Il est recommandé de demander :

• une syntaxe standard ;
• peu de styles personnalisés ;
• des identifiants sans espaces ni caractères spéciaux ;
• des libellés courts ;
• l’absence de fonctionnalités expérimentales ;
• un code compatible avec l’outil cible.

Un diagramme très élaboré peut fonctionner dans un éditeur récent mais échouer dans une plateforme qui utilise une version plus ancienne de Mermaid.

Étape 5 : tester le résultat dans un moteur Mermaid

Copier le résultat dans Mermaid Live Editor ou dans l’environnement final. Cette vérification permet de contrôler :

• l’absence d’erreur de syntaxe ;
• la lisibilité des libellés ;
• la direction des flèches ;
• l’ordre des étapes ;
• l’affichage des groupes ;
• la compatibilité avec le thème utilisé.

L’IA peut produire un code syntaxiquement plausible mais incorrect. Le rendu réel reste la référence.

Étape 6 : vérifier le contenu métier

Un diagramme peut s’afficher correctement tout en étant faux. Il faut contrôler :

• les composants réellement présents ;
• les dépendances ;
• le sens des échanges ;
• les conditions ;
• les noms des systèmes ;
• les cardinalités ;
• les cas d’erreur.

Cette étape est essentielle pour les architectures techniques, les schémas de données et les processus réglementaires.

Étape 7 : itérer avec des demandes ciblées

Les demandes successives doivent rester précises. Par exemple :

• « conserve tous les éléments, mais réduis le nombre de flèches croisées » ;
• « regroupe les composants externes dans un sous-graphe » ;
• « ajoute le scénario d’échec après une réponse HTTP 401 » ;
• « remplace les noms techniques par des libellés compréhensibles pour un public non développeur » ;
• « conserve la structure et corrige uniquement l’erreur de syntaxe ».

Demander une réécriture complète à chaque modification peut provoquer des changements involontaires.

Comment demander à l’IA un diagramme Mermaid de qualité ?

Utiliser une structure de prompt reproductible

Un modèle de consigne efficace peut suivre cette structure :

1. Objectif : expliquer un processus, une architecture ou une relation.
2. Public : développeurs, clients, équipe produit ou direction.
3. Type de diagramme : flux, séquence, entité-relation, état.
4. Sources : texte, liste de composants, documentation ou schéma existant.
5. Contraintes : version Mermaid, orientation, niveau de détail.
6. Sortie : code seul, code avec explication ou code accompagné d’hypothèses.
7. Validation : demander à l’IA de rechercher les erreurs avant de répondre.

Une consigne peut également demander à l’IA de signaler les informations manquantes au lieu de les inventer.

Demander explicitement les hypothèses

Pour éviter les hallucinations, ajouter une instruction comme :

N’invente aucune relation qui n’est pas indiquée. Si une information manque, liste-la séparément sous la rubrique « Hypothèses ».

Cette précaution est particulièrement utile pour les diagrammes d’architecture et les modèles de données.

Séparer le code et l’explication

Selon l’usage, demander l’un des formats suivants :

• « renvoie uniquement le code Mermaid » pour un copier-coller direct ;
• « renvoie le code puis une explication des choix » pour apprendre ;
• « renvoie les erreurs potentielles et une version corrigée » pour du dépannage.

Lorsque le code doit être copié dans un outil, préciser qu’il ne faut pas ajouter de balises Markdown autour du résultat. Une réponse entourée de triples accents inverses peut être pratique dans une conversation, mais elle doit parfois être retirée avant le collage.

Exemples de demandes selon le type de diagramme

Créer un organigramme

Demander à l’IA de représenter les décisions et les branches :

Génère un flowchart Mermaid orienté de gauche à droite. Le processus commence par la réception d’une commande. Vérifie le stock. Si le produit est disponible, confirme la commande et déclenche la livraison. Sinon, informe le client et clôture le processus. Utilise des libellés courts et affiche clairement les deux chemins.

Le mot « si » doit généralement correspondre à un nœud de décision. Une IA peut proposer un format comme `A{Stock disponible ?}` avec deux sorties distinctes.

Créer un diagramme de séquence

Préciser les participants et l’ordre des échanges :

Crée un diagramme de séquence Mermaid avec les participants Client, Frontend, API et Base de données. Le client soumet un formulaire. Le frontend appelle l’API. L’API valide les données, enregistre la demande et renvoie une confirmation. Ajoute un scénario d’erreur si la validation échoue.

Il est utile de demander une distinction entre les réponses réussies et les erreurs, par exemple avec des blocs `alt` ou `else`.

Créer un modèle entité-relation

Fournir les tables, les champs et les cardinalités :

Génère un diagramme `erDiagram` avec les entités Client, Commande et Produit. Un client peut avoir plusieurs commandes. Une commande contient plusieurs produits et un produit peut apparaître dans plusieurs commandes. Ajoute les clés primaires et les clés étrangères.

L’IA doit être invitée à signaler les informations absentes, notamment les champs de liaison nécessaires pour une relation plusieurs-à-plusieurs.

Créer une machine à états

Décrire les états et les événements :

Crée un `stateDiagram-v2` pour une commande. Les états sont Nouvelle, Payée, Préparée, Expédiée, Livrée et Annulée. Une commande nouvelle peut être payée ou annulée. Une commande payée peut être préparée. Affiche les transitions autorisées.

Ce format convient aux commandes, tickets de support, utilisateurs, workflows de validation et déploiements.

Comment corriger une erreur Mermaid avec l’IA ?

Lorsqu’un rendu échoue, transmettre à l’IA :

1. le code complet ;
2. le message d’erreur exact ;
3. l’outil utilisé ;
4. la version connue de Mermaid ;
5. le résultat attendu.

Prompt de dépannage :

Voici un diagramme Mermaid qui ne s’affiche pas. Identifie la cause probable à partir du message d’erreur, puis renvoie une version corrigée. Ne modifie pas la logique métier et évite les fonctionnalités expérimentales. Erreur : [message]. Environnement : [outil ou plateforme].

Erreurs fréquentes

• Identifiants ambigus : utiliser des identifiants simples comme `api`, `client` ou `db`, puis afficher un libellé plus explicite.
• Caractères spéciaux : les parenthèses, guillemets, deux-points ou crochets peuvent avoir une signification particulière.
• Syntaxe d’un autre type de diagramme : une instruction valide dans `flowchart` ne l’est pas forcément dans `sequenceDiagram`.
• Version incompatible : certaines fonctionnalités ne sont pas disponibles dans tous les moteurs.
• Diagramme trop large : une orientation horizontale peut devenir illisible sur mobile.
• Libellés trop longs : raccourcir les textes ou répartir le contenu sur plusieurs nœuds.

Il faut éviter de supprimer une ligne au hasard. La correction doit préserver le sens du diagramme.

Comment intégrer un diagramme Mermaid dans une documentation ?

Dans un fichier Markdown

Les plateformes compatibles permettent souvent d’utiliser une section Mermaid dédiée. La syntaxe exacte dépend du site, du générateur ou du dépôt concerné.

Avant la publication, contrôler :

• le rendu dans l’aperçu ;
• l’affichage sur mobile ;
• la lisibilité en mode sombre ;
• la présence d’un texte alternatif ou d’une description ;
• l’export éventuel en SVG ou PNG.

Dans Git

Stocker le code Mermaid dans un fichier Markdown permet de bénéficier :

• de l’historique des modifications ;
• des revues de code ;
• des comparaisons entre versions ;
• de la synchronisation avec la documentation technique.

Un message de commit peut préciser la nature du changement, par exemple : « ajout du parcours d’authentification » ou « mise à jour du schéma de données ».

Dans une présentation

Le SVG est généralement préférable au PNG lorsque l’outil l’accepte, car il conserve une bonne qualité lors du redimensionnement. Vérifier toutefois que les polices, couleurs et icônes restent correctement interprétées.

Sécurité, confidentialité et limites de l’IA

Ne pas envoyer à un modèle public :

• des clés API ;
• des mots de passe ;
• des données personnelles ;
• des informations confidentielles ;
• des détails d’architecture sensibles ;
• du code propriétaire non autorisé.

Remplacer les noms réels par des noms génériques lorsque le diagramme sert uniquement à tester une structure.

L’IA peut aussi :

• inventer des composants ;
• omettre une exception ;
• inverser une relation ;
• confondre une séquence avec une architecture ;
• générer une syntaxe non prise en charge ;
• produire un diagramme visuellement correct mais techniquement faux.

Une validation humaine reste donc indispensable.

Combien coûte la création de diagrammes Mermaid avec une IA ?

Mermaid est un projet open source et la syntaxe peut être utilisée gratuitement dans de nombreux projets. Le coût dépend principalement de l’outil d’IA et de l’environnement choisi :

• certains modèles proposent une formule gratuite avec des limites ;
• les formules payantes offrent généralement davantage de volume ou de fonctionnalités ;
• les outils spécialisés peuvent fonctionner avec un abonnement ;
• l’hébergement et les fonctions collaboratives peuvent être facturés séparément.

Pour quelques diagrammes ponctuels, un éditeur Mermaid et une IA disposant d’un accès gratuit peuvent suffire. Pour une équipe, il faut comparer la confidentialité, la collaboration, l’export, la gestion des versions et les limites d’utilisation.

Quand utiliser l’IA et quand dessiner manuellement ?

L’IA est particulièrement adaptée lorsque :

• une documentation textuelle existe déjà ;
• le diagramme contient beaucoup de composants ;
• plusieurs variantes doivent être produites ;
• une première ébauche est nécessaire rapidement ;
• le code Mermaid doit être maintenable et versionné.

Une création manuelle peut être préférable lorsque :

• le diagramme est très court ;
• la mise en page doit être contrôlée au pixel près ;
• le rendu doit respecter une charte graphique stricte ;
• le schéma est destiné à une présentation commerciale ;
• aucune erreur d’interprétation n’est acceptable.

La meilleure approche consiste souvent à utiliser l’IA pour générer une première version, puis à reprendre manuellement la structure, les libellés et la mise en page.

Bonnes pratiques à retenir

• Décrire précisément le processus avant de demander un diagramme.
• Choisir le type Mermaid correspondant à l’objectif.
• Indiquer la plateforme de rendu et la version si elle est connue.
• Demander une syntaxe standard et compatible.
• Limiter le nombre d’éléments sur un même diagramme.
• Tester le code dans le moteur Mermaid utilisé en production.
• Vérifier le contenu métier, pas seulement la syntaxe.
• Demander à l’IA de signaler ses hypothèses.
• Ne jamais transmettre de données confidentielles sans autorisation.
• Conserver les diagrammes sous forme de texte dans un système de versioning.
• Ajouter une explication ou une description pour les lecteurs qui ne peuvent pas voir le schéma.
• Prévoir une mise à jour du diagramme lorsque l’architecture ou le processus évolue.

Conclusion

Utiliser l’IA pour créer des diagrammes Mermaid permet de transformer rapidement une description textuelle en flowchart, diagramme de séquence, modèle entité-relation ou machine à états. La méthode la plus fiable consiste à fournir un contexte précis, demander une syntaxe compatible, tester le résultat dans un moteur Mermaid, puis vérifier manuellement la logique représentée.

L’IA doit servir d’accélérateur, pas de remplacement à la validation technique. Avec des prompts structurés, des données non sensibles et une vérification systématique du rendu, Mermaid devient un format pratique pour documenter des processus, des architectures et des systèmes directement dans un environnement versionné.