Mermaid : diagrammes, schémas et graphiques dans markdown

Mermaid est un langage qui permet de créer des diagrammes dynamiques directement dans des fichiers Markdown c'est à dire en mode texte.

Il est très utile pour représenter visuellement des concepts complexes sous forme de graphiques, schémas, diagrammes (comme des diagrammes de flux, des organigrammes, des graphiques Gantt, etc.) dans un format simple et lisible.

Un beau schéma vaut mille mots de markdown.

Mermaid s'intègre directement avec des plateformes et outils de documentation comme GitHub, GitLab, Docusaurus, MkDocs, ou Jekyll. Ainsi on peut inclure des diagrammes légers dans des fichiers README ou des wikis sans avoir besoin de les exporter en images.... images qui seront souvent non modifiables par les autres personnes participant à un projet car elles n'auront pas les sources tandis qu'avec Mermaid la source de l'image sera dans le document.

Le résultat étant généré à la volée en SVG (vectoriel) il s'adaptera à la résolution sans difficulté ainsi qu'à la préférence de thème, clair ou sombre (dark mode).

Exemples

La syntaxe de mermaid est assez basique, mais efficace.

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

La première ligne définit le type de diagramme et les suivantes la logique que l'on souhaite écrire. Remarquez qu'il n'y a pas d'instruction de positionnement de bloc, on s'attache juste à décrire les relations, et la bibliothèque JavaScript se charge du reste en transformant ce texte en un beau schéma.

On peut même générer des flux Git. 🤓

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit

Voici un diagramme de séquence bien complexe à dessiner, et pourtant simple à écrire en texte.

sequenceDiagram
    Gitlab->>Gitlab: reçoit un Push sur main
    Gitlab->>Runner: Lance un runner
    Runner->>Serveur: Connexion SSH
    Runner->>Serveur: Envoie les instructions shell du job
    Serveur-->>Gitlab: Connexion SSH vers Gitlab
    Serveur-->>Gitlab: git pull
    Gitlab-->>Serveur: Fichiers
    Runner->>Gitlab: Retourne les logs
    Note over Runner, Serveur: Fin

Voici le rendu sur GitHub avec en bonus quelques boutons pour zoomer, se déplacer, copier, etc.

Avantages

• C'est du texte.
• C'est modifiable.
• C'est versionnable.
• C'est adapté aux wikis.
• C'est multi-plateforme.
• C'est compris par GitHub et GitLab.

Inconvénients

• Il faut a priori connaître sa syntaxe (encore une autre...) (mais... des outils existent)

Support par GitHub et GitLab

Les deux plateformes les plus répandues de versionnement de code source supportent nativement Mermaid, ce qui est un grand avantage pour documenter vos projets, vos fichiers README.md de manière compréhensible et remplacer de longues explications de texte par des schémas limpides.

Documentation de GitHub

Documentation de GitLab

Documentation officielle

La documentation de Mermaid est très bien conçue et vous permet rapidement de cerner tout ce que permet la bibliothèque

Éditeurs en ligne

Pour faciliter les opérations, des éditeurs en ligne très bien conçus vous permettent de partir de modèles et de vous adapter progressivement à la syntaxe avec un aperçu du résultat.

• Mermaid Live Editor - gratuit, très souple, affichage plein écran et quelques options de mise en forme.

Il permet aussi le partage par URL c'est-à-dire d'encoder le contenu dans l'adresse et de la diffuser pour retrouver le schéma d'origine, par exemple pour le résultat ci-dessus :

https://mermaid.live/edit#pako:eNo1T8tOxDAM_BUr5-4P9IDUBwcQW0A9tnuwErON2CTFSYBV0w_iO_gxslvWkqXxaGZsL0I6RaIUbyf3JSfkMFrIVQ1d_A4H2O3ukpyIc8OJPChn7e9PBmThsX_uEtSboR6ql4erHpqNaYd5mvfnShlttyC8QO0DU7qJmmXZI2ts6wI88SdFhv71aV3_z7gGJibvXWSZ9_qAQX9E8gnuh6btDiAKYYgNapXfWC6-UYSJDI2izFAhv49itGvWYQyuP1spysCRCsEuHqfbEGeFgVqNR0azkesfwYJfFw

• Mermaidchart - freemium

• Mermaid ASCII - projet open-source

Génère des rendus en ASCII art (ou dans un Terminal).

$ cat test.mermaid
graph LR
A --> B & C
B --> C & D
D --> C

$ mermaid-ascii --file test.mermaid
+---+     +---+     +---+
|   |     |   |     |   |
| A |---->| B |---->| D |
|   |     |   |     |   |
+---+     +---+     +---+
  |         |         |
  |         |         |
  |         |         |
  |         |         |
  |         v         |
  |       +---+       |
  |       |   |       |
  ------->| C |<-------
          |   |
          +---+

Pimp my mermaid

Mermaid est un projet open source, ce qui signifie qu'il est possible de l'étendre ou de le modifier pour des besoins spécifiques si nécessaire.

Enfin, on peut avoir accès à des thèmes de couleur

• par défaut - pour tous les diagrammes.
• neutre - idéal pour les documents en noir et blanc qui seront imprimés.
• sombre - convient bien aux éléments de couleur sombre ou au mode sombre.
• forêt - avec des nuances de vert.
• base - le seul thème qui peut être modifié

Bref, c'est rudement pratique, on le prend en main facilement et vous serez fiers de pouvoir documenter vos projets, wiki, issues avec de beaux schémas compréhensibles.