Les diagrammes Mermaid dans GitHub et GitLab

La syntaxe

Dans n’importe quel fichier Markdown, ouvrez un bloc de code avec trois accents graves suivis de mermaid, collez le diagramme et fermez le bloc :

```mermaid
flowchart LR
  A[Push] --> B[Tests CI] --> C{Réussis ?}
  C -->|Oui| D[Déploiement]
  C -->|Non| E[Prévenir l’auteur]
```

GitHub affiche les blocs Mermaid depuis février 2022, dans les fichiers Markdown, les issues, les pull requests, les discussions et les wikis. GitLab les affiche dans le Markdown de l’ensemble du produit, y compris les merge requests et les wikis.

Là où c’est le plus utile

• README : montrer le fonctionnement du service, ou le parcours utilisateur principal, directement sur la page du dépôt.
• Notes d’architecture (ADR) : comparer le flux actuel et le flux proposé.
• Pull requests : illustrer la modification d’un processus ou d’un workflow d’API à côté du code qui l’implémente.
• Issues : décrire un bug comme le chemin qui y mène.

Tenir les schémas à jour

Comme le diagramme est du texte dans le dépôt, il peut être relu et modifié dans la même pull request que le code. Une règle qui aide : quand une pull request modifie un flux, elle met aussi à jour le schéma.

Dépannage

• Le code s’affiche au lieu du diagramme : vérifiez que le langage du bloc est exactement mermaid et que le bloc est bien fermé.
• Un message d’erreur à la place du diagramme : une erreur de syntaxe, souvent des parenthèses sans guillemets ou le mot « end » ; voir l’aide-mémoire de la syntaxe.
• Un rendu différent de votre éditeur : chaque plateforme embarque sa propre version de Mermaid, et les fonctions très récentes peuvent manquer. Restez sur la syntaxe de base pour la portabilité.
• Un très grand schéma devient illisible : découpez-le en plusieurs diagrammes.

Générer plutôt que taper

Pour un processus décrit en mots, vous pouvez générer le schéma avec Flowchartio, l’exporter en Mermaid (.mmd) et coller le contenu du fichier dans le bloc de code. Les couloirs sont exportés en sous-graphes, expliqués dans sous-graphes et styles.

Les autres outils qui affichent Mermaid nativement sont présentés dans Mermaid dans Notion, Obsidian et les outils de documentation.