Introduction : dessiner des diagrammes en écrivant du texte

À retenir — Mermaid transforme quelques lignes de texte en diagramme propre. Plus besoin de glisser des rectangles à la souris : vous décrivez, l'outil dessine. Le diagramme vit dans votre code, se versionne dans Git et se relit en clair.

Le problème que Mermaid résout

Vous connaissez la scène : un schéma fait sous Lucidchart ou PowerPoint il y a six mois. Le code a changé trois fois depuis, le schéma non. Personne ne le rouvre parce que le rouvrir veut dire repositionner douze flèches à la main. Le diagramme est devenu un mensonge poli.

Mermaid règle ça en traitant le diagramme comme du code. Au lieu de dessiner, vous écrivez :

flowchart LR
    Idee[Idée] --> Texte[Texte Mermaid] --> Diagramme[Diagramme rendu]

Ces quatre lignes produisent le schéma que vous voyez juste au-dessus. Changez un mot, le dessin se met à jour. Collez-le dans un fichier .md, et il se versionne, se compare dans une pull request et se relit même sans le rendre.

:::key[L'idée maîtresse] Un diagramme Mermaid est du texte. Tout ce qui est vrai pour du code l'est pour lui : versionnable, comparable ligne à ligne, modifiable au clavier, copiable, généré par un script ou une IA. :::

Concrètement, qu'est-ce que Mermaid ?

Mermaid est une bibliothèque JavaScript qui lit une syntaxe textuelle simple et génère un diagramme SVG (une image nette à n'importe quelle taille). Vous n'avez rien à installer pour commencer : l'outil tourne déjà dans les endroits où vous écrivez tous les jours.

Autrement dit, le diagramme du début de ce chapitre n'est pas une capture d'écran : c'est du texte Mermaid que la plateforme a rendu en direct. Vous lirez ainsi des dizaines de diagrammes réels au fil de la formation.

Votre tout premier diagramme

La règle d'or tient en une phrase : la première ligne déclare le type de diagramme, le reste le décrit. Voici un organigramme minimal.

flowchart TD
    A[Le visiteur arrive] --> B{Est-il connecté ?}
    B -->|Oui| C[Afficher le tableau de bord]
    B -->|Non| D[Afficher la page de connexion]

Décortiquons chaque morceau :

• flowchart TD — le type (organigramme) et la direction (TD = Top-Down, de haut en bas).
• A[...] — un nœud nommé A, dont le texte affiché est entre crochets.
• --> — une flèche qui relie deux nœuds.
• {Est-il connecté ?} — un nœud en forme de losange (les accolades), la forme conventionnelle d'une décision.
• -->|Oui| — une flèche avec une étiquette posée dessus.

Vous n'avez positionné aucun élément : Mermaid a calculé la mise en page tout seul. C'est tout l'intérêt — vous décrivez la logique, pas les coordonnées.

:::tip[Le réflexe qui fait gagner du temps] Donnez à vos nœuds des identifiants courts et parlants (B pour une décision, dbUser pour une table) plutôt que de longs libellés répétés. L'identifiant sert à relier ; le texte entre crochets sert à afficher. Les deux sont indépendants. :::

Anatomie d'un fichier Mermaid

Tout diagramme suit le même squelette, quel que soit le type :

flowchart LR
    L1["1 · Déclaration du type"] --> L2["2 · Définition des éléments"] --> L3["3 · Liens entre éléments"]
    L3 --> L4["4 · Style (optionnel)"]

1. Déclaration — flowchart, sequenceDiagram, classDiagram, gantt… (chapitres suivants).
2. Éléments — nœuds, participants, classes, tâches selon le type.
3. Liens — flèches, messages, relations.
4. Style — couleurs et thèmes, en option et toujours en dernier.

Tant que vous gardez cet ordre en tête, passer d'un type de diagramme à l'autre devient simple : seul le vocabulaire change, la structure reste.

Pourquoi écrire ses diagrammes plutôt que les dessiner ?

Le prix à payer : vous perdez le contrôle pixel par pixel. Pour un poster marketing, gardez votre outil graphique. Pour de la documentation technique qui doit rester juste dans le temps, Mermaid gagne presque toujours.

:::warning[Là où Mermaid n'est pas le bon outil] Mermaid excelle sur les diagrammes structurés (flux, séquences, schémas de données). Il n'est pas fait pour le dessin libre, les maquettes d'interface fidèles ou les illustrations artistiques. Choisir Mermaid pour ça, c'est forcer une clé dans la mauvaise serrure. :::

Ce que vous saurez faire à la fin

Cette formation est un tour complet et pratique de Mermaid. Au fil des chapitres, vous apprendrez à produire :

mindmap
  root((Mermaid))
    Flux
      Flowchart
      Diagramme de séquence
    Structure
      Diagramme de classes
      Diagramme d'états
      Schéma de base de données
    Projet
      Gantt
      Parcours utilisateur
    Maîtrise
      Thèmes et couleurs
      Configuration
      Workflow et IA

Chaque chapitre suit la même promesse que ce site : des exemples concrets, du copier-coller qui marche, et des diagrammes que vous pouvez reprendre tels quels dans vos projets.

En résumé

• Mermaid transforme du texte en diagramme : versionnable, modifiable au clavier, lisible en clair.
• Il fonctionne déjà dans GitHub, Notion, VS Code et bien d'autres, sans installation.
• Tout diagramme commence par une ligne qui déclare son type, puis décrit éléments et liens.
• Il brille sur les diagrammes structurés de documentation technique, pas sur le dessin libre.

Au chapitre suivant, on attaque le diagramme le plus utilisé de tous : le flowchart. C'est lui qui ouvre 80 % des besoins, et une fois ses formes et ses flèches maîtrisées, le reste de Mermaid devient une variation sur le même thème.