Quand on écrit de la documentation ou qu’on conçoit un projet technique, il arrive un moment où un schéma vaut mieux qu’un long discours. Diagrammes de flux, organigrammes, UML… ces visuels aident à clarifier les idées complexes. Mais créer ces schémas est souvent pénible : outils lourds, interfaces graphiques, fichiers séparés… et difficile à maintenir dans du code ou de la doc versionnée.

C’est là que Mermaid entre en scène.

C’est quoi Mermaid ?

Mermaid est un outil qui permet de générer des diagrammes à partir de texte. C’est un langage de script simple, lisible et intégré dans de nombreux outils comme :

  • VS Code (via des extensions)
  • GitHub (dans les fichiers .md)
  • Obsidian
  • GitLab
  • Notion
  • Docusaurus, MkDocs, etc.

En gros, vous écrivez du pseudo-code dans un bloc de texte, et Mermaid le transforme automatiquement en un diagramme.

Exemple concret : un diagramme de flux

flowchart TD
    A[Début] --> B{Choix ?}
    B -->|Oui| C[Option 1]
    B -->|Non| D[Option 2]
    C --> E[Fin]
    D --> E[Fin]
flowchart TD A[Début] --> B{Choix ?} B -->|Oui| C[Option 1] B -->|Non| D[Option 2] C --> E[Fin] D --> E[Fin]

Ce simple bloc donne un diagramme de flux clair en quelques lignes.

flowchart TD = un diagramme orienté de haut en bas

Les flèches montrent les relations

Les textes entre crochets ou accolades indiquent des formes différentes (rectangles, losanges…)

C’est lisible, rapide à écrire, et surtout intégrable directement dans vos fichiers Markdown ou votre documentation.

Pourquoi c’est utile dans la documentation ?

  • Toujours à jour avec le texte
    Pas besoin de fichiers SVG ou PNG à re-exporter. Vous changez une ligne de texte, le schéma suit.

  • Versionnable dans Git
    Comme Mermaid est basé sur du texte, il peut être versionné comme du code. Pratique pour les équipes.

  • Reproductible partout
    Pas besoin d’un logiciel particulier. Si votre doc supporte Mermaid, tout le monde voit le diagramme.

  • Gagnez du temps
    Pas besoin de déplacer des blocs à la souris pendant 10 minutes. Tout se fait au clavier.

Et en conception ?

Mermaid supporte aussi :

  • Les diagrammes de séquence (super utiles pour représenter des échanges entre services)
  • Les diagrammes de Gantt
  • Les diagrammes d’état
  • Le modèle de classes UML
  • Des cartes d’entités-relation (ERD)
  • Des mindmaps (avec des plugins)

Par exemple, pour un diagramme de séquence :

sequenceDiagram
    participant Client
    participant Serveur

    Client->>Serveur: Requête HTTP
    Serveur-->>Client: Réponse JSON
sequenceDiagram participant Client participant Serveur Client->>Serveur: Requête HTTP Serveur-->>Client: Réponse JSON

Ce type de diagramme est précieux pour expliquer un flux d’API, un échange asynchrone, ou une architecture microservices.

Comment l’utiliser ?

Voici quelques moyens simples pour commencer :

  • Sur GitHub : les blocs ```mermaid dans un .md sont automatiquement rendus.
  • Dans Obsidian : installez le plugin Mermaid natif.
  • Via un éditeur en ligne : https://mermaid.live
  • Dans VS Code : extension « Markdown Preview Mermaid Support »

Pour les développeurs, rédacteurs techniques et chefs de projet, Mermaid est un outil simple, puissant et moderne pour améliorer la clarté de vos documents et la collaboration au sein des équipes.