Diagrammes Mermaid dans Markdown

Mermaid est une façon de dessiner des diagrammes avec du texte. Tu écris quelques lignes courtes. Un lecteur compatible avec Mermaid les transforme en image : un organigramme, une chronologie, un graphique.

Tu peux garder le diagramme dans un fichier Markdown ordinaire. Il n’y a pas d’image à exporter ni d’outil de dessin à ouvrir. Pour modifier le diagramme, tu modifies le texte.

Le bloc de code mermaid

Un diagramme Mermaid vit dans un bloc de code délimité. Une clôture, ce sont trois accents graves. Après la clôture ouvrante, écris mermaid comme langage :

```mermaid
flowchart LR
    A --> B
```

La première ligne dans le bloc indique de quel type de diagramme il s’agit. Ici, c’est flowchart LR. Tout ce qui suit cette ligne décrit le diagramme.

Les lignes qui commencent par %% sont des commentaires. Le lecteur les ignore.

Exemple 1 : un organigramme avec une décision

```mermaid
flowchart TD
    Start[Écrire la note] --> Check{Est-ce clair ?}
    Check -->|Oui| Publish[La partager]
    Check -->|Non| Edit[La réécrire]
    Edit --> Check
```

Comment le lire :

Exemple 2 : un diagramme de séquence

Un diagramme de séquence montre qui parle à qui, dans l’ordre.

```mermaid
sequenceDiagram
    participant U as Utilisateur
    participant S as Serveur
    U->>S: Ouvrir la page
    S-->>U: Envoyer la page
    U->>S: Se connecter
    S-->>U: Bienvenue
```

Exemple 3 : un diagramme circulaire

```mermaid
pie title Temps passé sur un projet
    "Écriture" : 40
    "Lecture" : 25
    "Réunions" : 15
    "Autre" : 20
```

Chaque part est une étiquette entre guillemets, un deux-points et un nombre. Le nombre doit être supérieur à zéro.

Autres types de diagrammes

Mermaid peut dessiner bien d’autres types. Les plus courants :

Chaque type a son propre premier mot et ses propres règles. La documentation de Mermaid a une page pour chacun.

Où les diagrammes Mermaid sont dessinés

GitHub dessine les blocs Mermaid dans les fichiers Markdown, les tickets, les discussions, les pull requests et les wikis. Il suffit du bloc de code mermaid. De nombreux éditeurs Markdown et applications de notes prennent aussi en charge Mermaid, mais pas tous.

Quand un lecteur ne prend pas en charge Mermaid, il traite généralement le bloc comme n’importe quel autre code. Tu vois le texte que tu as écrit, pas une image. Rien n’est perdu. Ce n’est simplement pas dessiné.

Erreurs courantes

L’indentation n’est pas nécessaire. La plupart des gens indentent les lignes d’un diagramme uniquement parce que c’est plus facile à lire.

Les chats IA et les agents écrivent du Mermaid

Les chats IA et les agents de programmation mettent souvent du Mermaid dans les plans, les spécifications et les notes de conception. Un organigramme est un moyen rapide de montrer des étapes. Un diagramme de séquence montre comment les parties d’un système se parlent.

Si un chat te donne un diagramme, copie tout le bloc de code, clôtures comprises, dans ton fichier Markdown. Si le diagramme ne se dessine pas, compare-le avec les erreurs ci-dessus. Des étiquettes courtes et une seule idée par diagramme rendent le texte plus facile à corriger.

Lire les diagrammes Mermaid

PilcrowMD dessine les diagrammes Mermaid sur Android et sur Mac, sans Internet. Sur Android, touche un diagramme pour le voir en plein écran. Sur Mac, Quick Look, Comparer et PDF affichent le bloc de code au lieu de l’image.

Questions fréquentes

Dois-je installer quelque chose pour écrire du Mermaid ? Non. Tu écris du texte brut dans un bloc de code. Il te faut seulement un lecteur qui le dessine.

Pourquoi vois-je du code au lieu d’un diagramme ? Soit le lecteur ne prend pas en charge Mermaid, soit le diagramme contient une erreur de syntaxe. Vérifie que le bloc commence par mermaid et que la première ligne nomme un vrai type de diagramme.

Puis-je changer l’apparence d’un diagramme ? Oui. Mermaid propose des options pour les couleurs, les formes et la disposition. Commence par les réglages par défaut. Ils suffisent pour la plupart des notes.

Aussi sur Mac : PilcrowMD pour Mac (bêta)