Vous avez un diagramme Mermaid dans un README ou un fichier Markdown et vous voulez vérifier son rendu avant de le publier ? Le lecteur Markdown gratuit de Fude affiche le code et le diagramme côte à côte, directement dans votre navigateur.

Mermaid transforme une syntaxe textuelle en diagramme intégré au document Markdown. Dans ce guide, vous allez ajouter un bloc de code Mermaid, le prévisualiser avec l'exemple Fude, tester les principaux types de diagrammes et corriger les erreurs de rendu courantes.

Le plus petit bloc Mermaid valide dans Markdown

Une source Mermaid doit être placée dans un bloc de code balisé mermaid :

```mermaid
flowchart LR
  Brouillon --> Relecture
  Relecture --> Publication
```

Les trois accents graves ouvrent et ferment le bloc de code. Le mot mermaid indique au lecteur compatible qu'il doit interpréter le contenu comme un diagramme, et non comme du code ordinaire.

La première ligne à l'intérieur du bloc définit le type de diagramme. Dans cet exemple :

flowchart crée un diagramme de flux ;
LR organise les éléments de gauche à droite ;
Brouillon --> Relecture crée deux nœuds reliés par une flèche.

Sans le mot mermaid après les trois premiers accents graves, un lecteur Markdown affiche normalement le code source, mais il ne peut pas deviner qu'un diagramme doit être généré.

Prévisualiser Mermaid avec Fude

Le lecteur Markdown gratuit de Fude utilise le même moteur de rendu que l'application desktop et l'exécute localement dans le navigateur.

Ouvrez le lecteur et choisissez Exemple Mermaid.
Remplacez les nœuds et les flèches du flowchart par votre propre source.
Observez le diagramme se mettre à jour dans le panneau d'aperçu.

Vous pouvez également coller un README ou un document .md complet contenant plusieurs diagrammes. Les titres, paragraphes, tableaux, blocs de code colorés et diagrammes Mermaid restent dans le même aperçu. Vous vérifiez ainsi le document que les lecteurs verront réellement plutôt qu'un dessin isolé de son contexte.

Le contenu saisi n'est pas envoyé au serveur. Tout le rendu reste dans l'onglet actuel, ce qui convient aux notes d'architecture, aux processus internes et aux diagrammes contenant des noms de projets confidentiels.

Si la syntaxe est invalide, Fude conserve la source sous le message d'erreur. Vous pouvez donc corriger le bloc sans perdre le reste du document.

Quel type de diagramme Mermaid choisir ?

La première ligne du bloc détermine le type de diagramme. Choisissez-la en fonction de l'information à transmettre :

Besoin	Première ligne	Usage courant
Montrer un processus ou une décision	`flowchart LR`	Parcours, pipeline, architecture simple
Montrer des échanges dans le temps	`sequenceDiagram`	Appels d'API, authentification, événements
Montrer les états d'un objet	`stateDiagram-v2`	Cycle de vie, machine à états, workflow
Montrer la structure du code	`classDiagram`	Classes, interfaces et dépendances
Montrer un modèle de données	`erDiagram`	Entités, relations et cardinalités
Montrer un planning	`gantt`	Phases, dépendances et échéances
Montrer des branches Git	`gitGraph`	Stratégie de branches et historique
Organiser des idées	`mindmap`	Notes, concepts et arborescences

Les quatre types les plus fréquents dans une documentation technique sont détaillés ci-dessous. Les autres utilisent le même principe : une déclaration sur la première ligne, puis la source du diagramme.

Exemple de flowchart

Les flowcharts conviennent aux arbres de décision, pipelines de build, parcours d'accueil et interactions entre services.

Le texte entre crochets devient le libellé lisible d'un nœud. Les accolades créent une décision. Des libellés comme |Oui| précisent le sens d'une connexion.

Remplacez LR par TD lorsqu'une disposition verticale s'adapte mieux à la page :

Sur mobile, changer la direction du diagramme apporte souvent un meilleur résultat que l'ajout de styles ou de nœuds supplémentaires.

Exemple de diagramme de séquence

Un diagramme de séquence représente des messages échangés dans le temps. Il convient aux appels d'API, connexions, traitements asynchrones et interactions entre une application et une base de données.

Les participants apparaissent de gauche à droite. Les flèches pleines représentent naturellement une requête, tandis que les flèches en pointillés permettent de distinguer une réponse. La source reste compacte même lorsque plusieurs acteurs interviennent.

Exemple de diagramme de classes

Les diagrammes de classes décrivent des types et leurs relations. Dans une documentation technique, ils donnent une vue structurelle rapide sans remplacer une référence d'API complète.

Restez sélectif. Afficher chaque propriété et chaque méthode transforme rapidement une carte utile en seconde version du code, plus difficile à maintenir.

Exemple de diagramme entité-association

Les diagrammes entité-association résument les données stockées et leurs cardinalités. Ils sont particulièrement utiles dans les notes d'architecture et les plans de migration.

Ce diagramme ne remplace ni le vrai schéma ni les migrations. Il sert de vue d'ensemble lisible avant d'entrer dans les détails d'implémentation.

Écrire une source Mermaid lisible et portable

Un diagramme peut être valide dans votre lecteur et devenir difficile à maintenir après plusieurs modifications. Quelques conventions évitent la plupart des problèmes.

Séparer les identifiants des libellés

Utilisez des identifiants courts et stables dans les relations, puis placez le texte affiché entre crochets et guillemets :

Vous pourrez modifier « Relecture technique » sans devoir renommer toutes les relations qui utilisent review. Les guillemets rendent aussi les espaces, les accents et la ponctuation moins ambigus pour l'analyseur Mermaid.

Ajouter des commentaires dans la source

Une ligne commençant par %% est un commentaire Mermaid et n'apparaît pas dans le diagramme :

Les commentaires sont utiles pour expliquer une contrainte de mise en page ou la raison d'une relation sans alourdir le rendu visuel.

Donner un titre et une description accessibles

Mermaid accepte accTitle et accDescr pour ajouter un titre et une description au SVG généré. Ces informations aident les lecteurs d'écran et donnent un équivalent textuel au schéma :

Le titre doit rester court. La description doit transmettre la conclusion utile du diagramme, pas énumérer chaque forme. La documentation d'accessibilité de Mermaid détaille aussi les descriptions sur plusieurs lignes.

Ne pas dépendre des interactions ou d'un thème précis

Fude rend les diagrammes en mode de sécurité strict et adapte leurs couleurs au thème du lecteur. Considérez donc le résultat comme un visuel statique : ne comptez pas sur une action click, du HTML dans un libellé ou une position exacte au pixel près. Cette règle améliore également la compatibilité avec les autres lecteurs Markdown.

Pourquoi un diagramme Mermaid ne s'affiche pas

Lorsqu'un diagramme échoue, conservez le reste du document et réduisez progressivement le bloc Mermaid jusqu'à obtenir la plus petite version fonctionnelle.

Le bloc de code n'indique pas Mermaid

Le bloc suivant est du code Markdown ordinaire, pas un diagramme Mermaid :

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

Ajoutez mermaid immédiatement après les accents graves d'ouverture.

Un mot réservé est utilisé comme libellé

Dans un flowchart, le mot end entièrement en minuscules peut être interprété comme la fin d'un sous-graphe. Écrivez End, END ou utilisez un identifiant distinct avec un libellé entre guillemets :

Le type de diagramme est mal orthographié

La première ligne doit contenir une déclaration prise en charge, par exemple flowchart, sequenceDiagram, classDiagram ou erDiagram. La casse compte pour des déclarations comme sequenceDiagram.

Un libellé rend la grammaire ambiguë

Certains signes de ponctuation ont aussi une signification dans Mermaid. Donnez un identifiant au nœud puis placez le texte lisible entre crochets :

Si un libellé complexe échoue encore, remplacez-le temporairement par un seul mot. Rétablissez le texte initial une fois la structure validée.

Le diagramme est trop grand pour la page

Un diagramme peut être valide et rester inconfortable à lire. Essayez une autre direction, divisez un grand schéma en deux diagrammes ciblés ou retirez les détails déjà présents dans le texte. Le diagramme doit clarifier le document, pas le recopier.

Deux lecteurs produisent un rendu légèrement différent

Mermaid évolue et les produits n'intègrent pas toujours la même version ou le même thème. Testez le diagramme dans sa destination finale, évitez de dépendre d'une disposition au pixel près et consultez la documentation officielle de Mermaid pour le type utilisé.

Compatibilité avec GitHub, GitLab et les lecteurs Markdown

GitHub prend en charge Mermaid dans les fichiers Markdown, les issues, les pull requests, les discussions et les wikis. GitLab prend également en charge les blocs Mermaid, mais chaque plateforme choisit sa propre version de la bibliothèque et ses propres règles de sécurité.

Un diagramme peut donc fonctionner dans Fude et échouer ailleurs s'il utilise une syntaxe ajoutée récemment, une configuration locale ou une interaction désactivée par la plateforme. Pour maximiser la portabilité :

privilégiez les types stables comme flowchart, sequenceDiagram, classDiagram et erDiagram ;
gardez des identifiants simples et des libellés entre guillemets ;
évitez les liens interactifs, le HTML et les réglages de thème indispensables à la compréhension ;
testez le document dans sa destination finale avant de le publier.

Un lecteur Markdown sans prise en charge de Mermaid affichera simplement le bloc de code. Le texte qui précède le diagramme doit donc continuer à expliquer son rôle.

Mermaid au milieu d'un vrai document Markdown

La force d'un visualiseur Mermaid intégré à un lecteur Markdown est le contexte. Un diagramme peut suivre directement son explication, à côté d'un tableau Markdown, d'exemples de code, de liens ou de listes de tâches.

Utilisez le texte pour expliquer pourquoi le système se comporte ainsi. Réservez le diagramme aux relations, aux directions et aux séquences. Ajoutez une courte phrase avant chaque schéma afin que son rôle reste compréhensible même dans un lecteur qui n'affiche pas Mermaid.

Si vous avez reçu un document .md inconnu, commencez par le guide consacré aux fichiers Markdown et à leur ouverture. Collez ensuite son contenu dans le lecteur Markdown en ligne et utilisez l'exemple Mermaid chaque fois que vous avez besoin d'une base propre.

Pour organiser une bibliothèque locale de documents Markdown avec thèmes, projets et lecture hors ligne, téléchargez Fude pour macOS.

Comment prévisualiser des diagrammes Mermaid en Markdown en ligne