Mermaid JS

Mermaid c’est une des meilleures découvertes pour documenter du code ou une architecture : tu écris du texte, ça devient un diagramme.

Ce que c’est

Mermaid est une bibliothèque JavaScript qui génère des diagrammes à partir d’une syntaxe textuelle inspirée du Markdown. L’idée : décrire un flux, une architecture ou une séquence avec quelques lignes de texte, et obtenir un schéma propre sans jamais ouvrir un outil graphique.

Supporté nativement dans GitHub, GitLab, Notion, Obsidian, et ce site (via shortcode {{< mermaid >}}).

Points forts

• Syntaxe simple à apprendre, proche du Markdown
• Diagrammes versionnés avec le code (dans les README, la doc)
• Intégration native GitHub — fonctionne directement dans les .md
• Large gamme de types : flowchart, séquence, Gantt, entité-relation, pie, mindmap…
• Éditeur en ligne pour prototyper rapidement : mermaid.live

Types de diagrammes

Les plus utilisés :

• Flowchart — flux de décisions, processus
• Sequence diagram — échanges entre services/acteurs
• Gantt — planning de projet
• ER diagram — modèle de base de données
• C4 diagram — architecture logicielle (niveaux contexte/conteneur)

Limites

• Mise en page non contrôlable finement (positionnement automatique)
• Gros diagrammes complexes peuvent devenir illisibles
• Pas d’interactivité native (hover, clic) sans JS supplémentaire
• Rendu peut varier légèrement selon la version de Mermaid utilisée

Tarifs

Entièrement gratuit et open-source (MIT). L’éditeur en ligne mermaid.live est aussi gratuit. Mermaid Chart (la version SaaS avec collaboration) propose un plan payant, mais l’outil de base ne nécessite aucun compte.

Alternatives

• draw.io — interface graphique, plus puissant pour les diagrammes complexes
• PlantUML — similaire, orienté UML, moins intégré dans les éditeurs modernes
• Excalidraw — pour les schémas visuels au style dessin à la main