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 :
flowchart TDsignifie de haut en bas (top to down). UtiliseLRpour de gauche à droite. Le motgraphfonctionne aussi à la place deflowchart.Start[Écrire la note]crée une boîte.Startest le nom court. Le texte entre crochets est l’étiquette.- Les accolades
{ }créent une forme de décision, un losange. -->dessine une flèche. Le texte entre barres verticales, comme|Oui|, est l’étiquette de la flèche.
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
```
participant U as Utilisateurcrée une colonne nommée Utilisateur. Le nom court estU.->>est une flèche pleine.-->>est une flèche en pointillés, souvent utilisée pour les réponses.- Le texte après les deux-points est le message.
- Les messages sont dessinés de haut en bas, dans l’ordre où tu les écris.
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 :
- Diagramme de Gantt : des tâches sur une chronologie.
- Diagramme de classes : les classes dans le code et leurs liens.
- Diagramme d’états : les états d’une chose et la façon dont elle passe de l’un à l’autre.
- Diagramme entité-relation : les tables d’une base de données et leurs liens.
- Parcours utilisateur : les étapes suivies par une personne.
- Carte mentale : des idées qui partent d’un centre.
- Chronologie : des événements dans l’ordre des dates.
- Graphe Git : les branches et les commits.
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
- Une petite faute de frappe casse tout le diagramme. Des mots-clés inconnus ou mal orthographiés l’empêchent de se dessiner. Si tu vois une erreur ou du texte brut, vérifie d’abord la première ligne et les flèches.
- Caractères spéciaux dans les étiquettes. Les crochets, les parenthèses et les caractères semblables peuvent perturber l’analyseur. Mets l’étiquette entre guillemets :
A["Enregistrer (brouillon)"]. - Le mot
enddans un organigramme. En minuscules,endcasse un organigramme. ÉcrisEndouEND, ou mets le mot entre guillemets. Il peut aussi poser problème dans les diagrammes de séquence. - Mauvaise clôture. Le langage après les accents graves doit être
mermaid. Sans lui, le lecteur voit un simple bloc de code.
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)