Les diagrammes techniques deviennent souvent obsolètes car leur modification nécessite de rechercher le fichier de conception d'origine, d'ouvrir une application distincte et d'exporter une autre image.Mermaid adopte une approche différente : le diagramme est défini sous forme de texte et stocké à côté de la documentation.
Pour ajouter Mermaid à Markdown, placez la définition du diagramme à l'intérieur d'un bloc de code clôturé avec le mermaid identifiant de langue.Utilisez le Aperçu de diagramme Mermaid pour restituer la syntaxe localement, corriger les erreurs, copier la clôture Markdown complète ou télécharger un SVG.
Ce guide commence par un petit organigramme et se développe vers des diagrammes de séquence, de classe, de Gantt, de carte mentale et de diagrammes d'entité-relation.
Mermaid en 30 secondes
Un bloc de base Mermaid ressemble à ceci :
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
La clôture d'ouverture indique à un moteur de rendu compatible que le contenu est de syntaxe Mermaid. flowchart LR sélectionne un organigramme disposé de gauche à droite.Les lignes restantes définissent les nœuds et les connexions.
Si la destination ne prend pas en charge Mermaid, les lecteurs verront généralement un bloc de code au lieu d'un diagramme.Cette solution de secours préserve la source, mais elle ne remplace pas la vérification de la compatibilité avant la publication.
Pourquoi utiliser des diagrammes textuels ?
Mermaid est particulièrement utile lorsqu'un schéma :
- appartient à la documentation contrôlée en version ;
- modifications ainsi que le code ou les procédures ;
- a besoin de différences de demande d'extraction significatives ;
- utilise des formes et des relations standard ;
- doit être modifiable sans fichier de conception propriétaire ;
- doit être régénéré en thèmes clairs et sombres.
Il est moins adapté aux illustrations détaillées, aux mises en page au pixel près, aux annotations à main levée ou aux conceptions visuelles nécessitant un placement manuel précis.Dans ces cas, utilisez un outil de dessin et exportez un SVG ou une image accessible.
Exemple 1 : Un organigramme
Les organigrammes décrivent un processus, une décision ou une règle de routage.
```mermaid
flowchart TD
A[Choose a DOCX file] --> B{File valid?}
B -->|Yes| C[Convert to Markdown]
B -->|No| D[Show an error]
C --> E[Review the output]
E --> F[Copy or download]
```
Syntaxe des clés :
TDsignifie de haut en bas.LRsignifie de gauche à droite.[Text]crée un nœud de processus rectangulaire.{Text}crée un nœud de décision.-->crée une connexion directionnelle.-->|Label|ajoute du texte à une connexion.
Utilisez des ID de nœud stables et courts tels que A or validate.Gardez l'étiquette visible entre parenthèses afin que la modification du libellé ne nécessite pas de modifier chaque connexion.
Ajouter un sous-graphe
Étapes liées au groupe de sous-graphes :
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
Utilisez des sous-graphiques lorsque le groupe communique la propriété, les limites du système ou les phases.N'ajoutez pas de boîte uniquement pour la décoration.
Exemple 2 : Un diagramme de séquence
Les diagrammes de séquence montrent les interactions dans l'ordre temporel.Ils fonctionnent bien pour les appels API, l'authentification, les flux de travail du navigateur et les systèmes pilotés par événements.
```mermaid
sequenceDiagram
autonumber
actor User
participant Browser
participant Converter
User->>Browser: Select DOCX file
Browser->>Converter: Pass local file data
Converter-->>Browser: Return Markdown
Browser-->>User: Show editable preview
```
Flèches communes :
->>envoie un message solide.-->>envoie une réponse en pointillés.participantdéclare un système ou un service.actordéclare un rôle humain ou externe.autonumberétiquette les interactions dans l'ordre.
Focus sur un scénario.Un diagramme de séquence qui tente de montrer chaque alternative et chaque fonction interne devient plus difficile à comprendre que le code.
Afficher un chemin alternatif
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /documents
alt Valid request
API-->>Client: 201 Created
else Invalid request
API-->>Client: 400 Bad Request
end
```
Utilisation alt, else, et end pour les branches significatives.Si la branche nécessite plusieurs pages d'explication, créez un lien vers la prose sous le diagramme.
Exemple 3 : Un diagramme de classes
Les diagrammes de classes décrivent les types, les propriétés, les opérations, l'héritage et les relations.
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
Cet exemple indique que MarkdownDocument hérite de Document.Utilisez les diagrammes de classes pour un modèle conceptuel, et non comme remplacement automatique d'une documentation de référence complète API.
Les bons diagrammes de classes omettent des détails qui n'aident pas le lecteur à comprendre la conception.Afficher chaque champ privé peut transformer le diagramme en une version moins consultable du code source.
Exemple 4 : Un diagramme de Gantt
Les diagrammes de Gantt affichent les tâches dans le temps.Ils sont utiles pour les plans de publication, les migrations et les projets de documentation.
```mermaid
gantt
title Documentation migration
dateFormat YYYY-MM-DD
section Preparation
Inventory content :done, inventory, 2026-11-03, 3d
Define templates :done, templates, after inventory, 2d
section Migration
Convert documents :active, convert, 2026-11-08, 7d
Editorial review :review, after convert, 5d
section Publish
Final validation :validate, after review, 2d
```
Gardez les dates explicites et utilisez les ID de tâche lorsqu'une tâche dépend d'une autre.N'oubliez pas qu'un diagramme stocké dans la documentation ne se mettra pas à jour lorsque le calendrier réel du projet changera.Attribuez la propriété pour le maintenir à jour.
Exemple 5 : Une carte mentale
Les cartes mentales organisent les idées autour d'un sujet central.
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
Les cartes mentales sont plus efficaces lors de la planification ou comme aperçu de haut niveau.Ils sont moins utiles pour des relations précises car la structure arborescente peut impliquer une hiérarchie où les concepts réels se chevauchent.
Exemple 6 : Un diagramme entité-relation
ER décrivent les entités de données et leurs relations.
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT }o--o{ TAG : uses
AUTHOR {
string id
string name
}
DOCUMENT {
string id
string title
datetime published_at
}
```
Utilisez un diagramme ER pour expliquer le modèle et un schéma ou un fichier de migration pour définir l'implémentation.Un diagramme peut omettre des index, des contraintes et des champs qui ne sont pas pertinents pour l'explication actuelle.
Aperçu Mermaid avant publication
L'écriture de schémas directement dans un long document Markdown rend les erreurs de syntaxe difficiles à isoler.Une boucle de prévisualisation ciblée est plus rapide :
- Ouvrez le Aperçu de diagramme Mermaid.
- Collez uniquement la définition du diagramme, sans la clôture de code externe.
- Rendre le diagramme.
- Lire toute erreur de syntaxe et corriger la zone référencée.
- Copier le clôturé Markdown généré.
- Téléchargez le SVG lorsque la destination a besoin d'un actif statique.
- Testez le Markdown final dans sa plateforme réelle.
L'aperçu s'affiche dans votre navigateur avec une configuration de sécurité stricte.Les rappels de diagramme et autres comportements interactifs peuvent être désactivés même si une autre installation de Mermaid le permet.Ce comportement conservateur est approprié pour un outil de prévisualisation général.
Erreurs courantes Mermaid
Le type de schéma est manquant
C' est faux:
A --> B
C' est vrai .
flowchart LR
A --> B
La première ligne identifie la grammaire du diagramme.
La ponctuation dans une étiquette interrompt l'analyse
Citer des étiquettes complexes :
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
Ceci est particulièrement utile pour les parenthèses, la ponctuation et les étiquettes qui ressemblent à une syntaxe.
Un Word réservé est utilisé de manière inattendue
Mermaid ont des mots-clés.La documentation officielle de l'organigramme prévient spécifiquement que les minuscules end peut casser un organigramme.Mettez-le en majuscule ou placez le texte visible à l'intérieur d'une étiquette de nœud entre guillemets :
flowchart LR
Start --> Finish["End"]
La barrière de code est incorrecte
L'identifiant de langue se situe immédiatement après les backticks d'ouverture :
```mermaid
flowchart LR
A --> B
```
N'indentez pas la clôture complète à moins que la syntaxe Markdown environnante ne l'exige.
Cela fonctionne sur une plateforme mais pas sur une autre
Mermaid évolue et les plates-formes peuvent utiliser différents moteurs de rendu, versions, paramètres de sécurité et types de diagrammes activés.Une fonctionnalité de syntaxe prise en charge par la dernière version de Mermaid peut échouer sur une plateforme utilisant une autre implémentation ou une version plus ancienne.
Préférer une syntaxe largement prise en charge pour les documents qui se déplacent entre les plates-formes.Testez des formes, des thèmes, des directives avancés et des types de diagrammes plus récents dans chaque destination requise.
Compatibilité des plateformes
La compatibilité doit être testée plutôt que supposée :
| La plateforme | Approche documentée actuelle | Remarque importante |
|---|---|---|
| GitHub | Utiliser un terrain clôturé mermaid block | GitHub documents rendus dans des fichiers Markdown, problèmes, discussions, demandes d'extraction et wikis |
| Le GitLab | Utiliser un bloc de code Mermaid dans GitLab Flavored Markdown | GitLab documente sa version Mermaid prise en charge ;les installations autogérées peuvent différer |
| Obsidian | Utiliser un terrain clôturé mermaid dans une note | Le moteur de rendu de Obsidian et les fonctionnalités prises en charge peuvent changer d'une version à l'autre. |
| Matériel pour MkDocs | Configurer une clôture personnalisée Mermaid | L'intégration du thème natif nécessite une documentation pymdownx.superfences configuration |
| Analyseur générique Markdown | Affiche souvent uniquement le code | Le rendu Mermaid nécessite généralement une intégration ou un plugin de build JavaScript |
Vérifiez la documentation officielle actuelle avant de vous fier à une fonctionnalité plus récente :
- GitHub : Création de schémas
- GitLab aromatisé Markdown
- Obsidian : Syntaxe de formatage avancée
- Matériel pour MkDocs : Schémas
- Mermaid référence syntaxique
Pour un site de documentation que vous contrôlez, épinglez la version de dépendance Mermaid et testez les mises à jour.Sinon, une modification mineure de la syntaxe peut modifier les diagrammes sur l’ensemble du site.
Mermaid et Accessibilité
Un SVG rendu ne communique pas automatiquement sa signification à chaque lecteur.Traitez le diagramme comme un résumé visuel et fournissez une explication équivalente en prose proche.
Pour l'organigramme de conversion précédent, ajoutez un texte tel que :
L'utilisateur sélectionne un fichier DOCX.Les fichiers valides sont convertis localement et affichés pour examen ;les fichiers invalides produisent une erreur.L'utilisateur peut ensuite copier ou télécharger les Markdown révisés.
Pratiques d'accessibilité :
- introduire ce que le schéma explique ;
- résumer la conclusion après des schémas complexes ;
- ne code pas le sens uniquement avec la couleur ;
- utiliser des étiquettes lisibles plutôt que des abréviations internes ;
- maintient un contraste suffisant dans les thèmes clairs et sombres ;
- évitez les diagrammes qui nécessitent une interaction précise avec la souris ;
- fournir une alternative sous forme de texte ou de tableau pour les informations essentielles ;
- exportez le SVG avec précaution lorsque le fichier statique doit porter un nom accessible.
Le code source est utile aux auteurs, mais il ne constitue pas nécessairement une bonne alternative textuelle pour les lecteurs.
Concevoir des diagrammes qui restent lisibles
Conserver un objectif par schéma
Un diagramme doit répondre à une question telle que « Que se passe-t-il après l'échec d'une requête ?ou "Quel service possède chaque magasin de données ?"S’il tente d’expliquer l’ensemble du système, divisez-le.
Préférer les étiquettes courtes
Mettez les explications détaillées en prose.Les étiquettes longues entraînent des nœuds étroits, des retours à la ligne difficiles et de grands diagrammes sur les écrans mobiles.
Utiliser intentionnellement la direction
Le flux de gauche à droite fonctionne bien pour les processus courts et les chemins de requête.Le flux de haut en bas s’adapte souvent mieux aux écrans étroits.Prévisualisez les deux avant de vous engager.
Limiter le style visuel
Les couleurs personnalisées peuvent entrer en conflit avec les thèmes du mode sombre ou de la plateforme.Commencez par les valeurs par défaut du moteur de rendu.Ajoutez des styles uniquement lorsqu'ils communiquent un sens et restent lisibles dans tous les thèmes requis.
Garder la source à proximité de son explication
Stocker le bloc Mermaid dans le même fichier Markdown lorsque cela est possible.Cela fait que la prose et le diagramme changent ensemble en une seule critique.
Mermaid vs une image statique
Choisir Mermaid lorsque :
- le schéma change fréquemment ;
- sont précieuses ;
- la mise en page utilise des types de diagrammes standards ;
- la plateforme de publication restitue Mermaid de manière fiable.
Choisissez SVG ou PNG lorsque :
- la conception nécessite un tracé manuel précis ;
- la destination ne restitue pas Mermaid ;
- l'apparence exacte doit rester fixe ;
- nécessite un actif autonome.
Un hybride utile consiste à conserver la source Mermaid et à exporter un SVG pour les destinations qui ne peuvent pas le restituer.Conservez la source à côté de l’actif exporté et documentez comment la régénérer.
Utilisation Markdown vers image pour le contenu rendu Markdown partageable, ou téléchargez SVG directement depuis le Aperçu de diagramme Mermaid lorsque le schéma lui-même est l'atout.
FAQ
Est-ce que Mermaid fait partie de la norme Markdown ?
N° A clôturé mermaid est une extension reconnue par les applications et systèmes de build compatibles.Un analyseur de base Markdown peut le restituer sous forme de code ordinaire.
Est-ce que GitHub restitue les diagrammes Mermaid ?
Oui.La documentation de GitHub décrit le rendu Mermaid dans les fichiers Markdown et plusieurs surfaces de collaboration.Testez une syntaxe plus récente car GitHub contrôle le moteur de rendu déployé et les paramètres de sécurité.
Puis-je utiliser Mermaid dans Obsidian ?
Obsidian documente les blocs de diagramme clôturés de style Mermaid dans les notes.La prise en charge des fonctionnalités peut changer avec le moteur de rendu de l'application, alors vérifiez les types de diagrammes complexes ou nouvellement introduits dans votre version installée.
Le Mermaid peut-il remplacer la documentation d'architecture ?
Non. Un diagramme est une vue d'un système.Associez-le à des décisions, à la propriété, à des contraintes, à des comportements d'échec et à des liens vers des interfaces ou des schémas faisant autorité.
Pourquoi mon diagramme s'affiche-t-il différemment en mode sombre ?
Les plateformes peuvent appliquer différents thèmes Mermaid, variables CSS, polices et arrière-plans.Évitez les couleurs codées en dur jusqu'à ce que vous ayez testé les deux thèmes.
Dois-je valider les fichiers SVG exportés ?
Validez un SVG lorsque la destination de publication a besoin d'un actif statique ou que le résultat rendu doit rester stable.Conservez également la source Mermaid et un processus de régénération documenté pour éviter que les deux versions ne dérivent.
Est-ce que Mermaid est sûr pour les schémas confidentiels ?
La confidentialité dépend de l'éditeur et du flux de publication.L'aperçu de WordToMD affiche le diagramme dans votre navigateur, mais la publication du Markdown ou du SVG sur un référentiel ou un site suit les contrôles d'accès de cette destination.
Conclusion de l'enquête
Mermaid rend les diagrammes maintenables car la source vit avec le Markdown.Commencez avec un petit bloc clôturé, choisissez le type de diagramme qui correspond à la question, prévisualisez la syntaxe et testez-la dans le moteur de rendu final.Utilisez de la prose pour expliquer la signification essentielle et exportez SVG lorsqu'une destination a besoin d'un élément statique.
Essayez les exemples dans le Aperçu de diagramme Mermaid, éditez la documentation environnante dans le Markdown Editeur, et gardez le diagramme suffisamment concentré pour qu'un futur contributeur puisse le comprendre et le mettre à jour sans redessiner la page entière.