Introduction et guide de référence rapide sur les diagrammes Mermaid pour les développeurs

Mermaid est un outil de diagrammes basé sur le texte, conçu pour ceux qui préfèrent écrire leurs diagrammes plutôt que de faire glisser des formes sur un canevas. Il utilise une syntaxe proche de Markdown pour décrire des organigrammes, des diagrammes de séquence, des diagrammes de classes, des machines à états, des frises chronologiques, des diagrammes de Gantt, des diagrammes entité-association et bien plus encore.

Pour un blog technique, Mermaid constitue une valeur par défaut très pertinente. Les diagrammes coexistent à côté de l’article, ils peuvent être revus via Git, et ils sont faciles à mettre à jour lorsque le système évolue. Les diagrammes sous forme d’images statiques ont l’air soignés jusqu’à la première modification d’architecture. Les diagrammes Mermaid ne sont pas parfaits, mais ils vieillissent beaucoup mieux.

Ce guide est une introduction pratique et une fiche de référence rapide sur Mermaid pour les développeurs, rédacteurs techniques et propriétaires de sites Hugo. Il fait partie du hub Outils de documentation en 2026 : Markdown, LaTeX, PDF et flux de travail d’impression.

Qu’est-ce que Mermaid ?

Mermaid est une syntaxe « diagramme sous forme de code ». Vous écrivez un petit bloc de texte, et Mermaid le rend sous forme de diagramme.

Un diagramme Mermaid de base ressemble à ceci :

ce code :

```mermaid
flowchart TD
    A[Écrire en Markdown] --> B[Ajouter le bloc Mermaid]
    B --> C[Rendre la page]
    C --> D[Publier le diagramme]
```

Produit ce diagramme :

L’idée importante est simple : la source du diagramme est du texte brut. Cela le rend searchable, révisable, portable et facile à conserver avec la documentation qu’il explique.

Pourquoi utiliser Mermaid dans un blog technique ?

Mermaid est utile lorsque votre article a besoin de plus que du seul texte mais de moins qu’un outil de design complet.

Utilisez Mermaid lorsque vous souhaitez expliquer :

• Les flux de requêtes et de réponses
• Les pipelines de déploiement
• Les dépendances entre services
• Les transitions d’état
• Les relations de bases de données
• Les parcours utilisateurs
• Les étapes de construction (build)
• La logique décisionnelle
• Les calendriers de projet

Je n’utiliserais pas Mermaid pour chaque visuel. Les captures d’écran, les croquis d’architecture faits main et les diagrammes marketing soignés ont toujours leur place. Mais pour la documentation technique, Mermaid est souvent l’option la plus facile à maintenir.

Introduction rapide à Mermaid

Utilisation de base en Markdown

En Markdown, utilisez un bloc de code clôturé avec mermaid comme langage :

```mermaid
flowchart LR
    A[Début] --> B[Traitement]
    B --> C[Terminé]
```

De nombreuses plateformes comprennent ce format directement. mermaid est l’un des identifiants de langage spéciaux — aux côtés de diff, geojson et autres — que certains moteurs de rendu traitent comme un type de bloc de premier ordre plutôt que comme une simple coloration syntaxique. Pour une analyse complète de la syntaxe des blocs clôturés et des identifiants de langage pris en charge, consultez le guide des blocs de code Markdown. Pour Hugo, le rendu dépend de votre thème ou de la configuration du site. Nous y reviendrons plus tard.

Tester les diagrammes avant la publication

Le flux de travail le plus simple est :

1. Écrire le diagramme dans votre fichier Markdown.
2. Le coller dans un éditeur Mermaid en direct ou une prévisualisation locale.
3. Corriger les erreurs de syntaxe.
4. Valider (commit) la source Markdown.
5. Vérifier la page rendue finale.

Cela évite le problème classique où un diagramme fonctionne avec un moteur de rendu mais échoue avec un autre à cause d’un petit détail syntaxique.

Syntaxe des organigrammes (Flowcharts)

Les organigrammes sont le type de diagramme Mermaid le plus courant. Utilisez-les pour les flux de travail, les algorithmes, les arbres de décision et les étapes système.

Organigramme de base

ce code :

```mermaid
flowchart TD
    A[L'utilisateur ouvre le site web] --> B{L'utilisateur est-il connecté ?}
    B -->|Oui| C[Afficher le tableau de bord]
    B -->|Non| D[Afficher la page de connexion]
```

Produit ce diagramme :

Directions des organigrammes

Les organigrammes Mermaid prennent en charge plusieurs directions :

TD - de haut en bas
TB - de haut en bas
BT - de bas en haut
LR - de gauche à droite
RL - de droite à gauche

Exemple :

ce code :

```mermaid
flowchart LR
    Navigateur --> CDN
    CDN --> ServeurWeb
    ServeurWeb --> BaseDeDonnées
```

Produit ce diagramme :

Pour les articles de blog, LR est souvent plus facile à lire pour les diagrammes d’architecture. Pour les processus étape par étape, TD est généralement préférable.

Formes de nœuds courantes

ce code :

```mermaid
flowchart TD
    A[Rectangle]
    B(Rectangle arrondi)
    C{Décision}
    D((Cercle))
    E[(Base de données)]
    F[[Sous-routine]]
```

Produit ce diagramme :

Flèches des organigrammes

ce code :

```mermaid
flowchart LR
    A --> B
    B --- C
    C -.-> D
    D ==> E
    E -- Étiquette --> F
```

Produit ce diagramme :

Sous-graphes

Utilisez les sous-graphes pour regrouper les parties liées d’un système.

ce code :

```mermaid
flowchart LR
    subgraph Client
        Navigateur
    end

    subgraph Backend
        API
        Worker
    end

    subgraph Stockage
        BD[(PostgreSQL)]
        Cache[(Redis)]
    end

    Navigateur --> API
    API --> BD
    API --> Cache
    API --> Worker
```

Produit ce diagramme :

Les sous-graphes sont puissants, mais utilisez-les avec prudence. Un diagramme avec six sous-graphes et vingt flèches est généralement le signe que l’article a besoin de deux diagrammes plus petits.

Syntaxe des diagrammes de séquence

Les diagrammes de séquence montrent les communications entre acteurs ou services au fil du temps.

ce code :

```mermaid
sequenceDiagram
    participant Utilisateur
    participant App
    participant API
    participant BD

    Utilisateur->>App: Cliquer connexion
    App->>API: POST /login
    API->>BD: Valider les identifiants
    BD-->>API: Enregistrement utilisateur
    API-->>App: Jeton d'accès
    App-->>Utilisateur: Afficher le tableau de bord
```

Produit ce diagramme :

Flèches de séquence courantes

->      Ligne pleine sans flèche
-->     Ligne pointillée sans flèche
->>     Ligne pleine avec flèche
-->>    Ligne pointillée avec flèche
-x      Ligne pleine avec croix
--x     Ligne pointillée avec croix

Barres d’activation

Les barres d’activation clarifient le moment où un participant effectue un travail.

ce code :

```mermaid
sequenceDiagram
    participant Client
    participant Serveur

    Client->>Serveur: Demander des données
    activate Serveur
    Serveur-->>Client: Réponse
    deactivate Serveur
```

Produit ce diagramme :

Alternatives et conditions

ce code :

```mermaid
sequenceDiagram
    participant Utilisateur
    participant API
    participant Paiement

    Utilisateur->>API: Soumettre la commande

    alt Le paiement réussit
        API->>Paiement: Facturer la carte
        Paiement-->>API: Approuvé
        API-->>Utilisateur: Commande confirmée
    else Le paiement échoue
        Paiement-->>API: Refusé
        API-->>Utilisateur: Afficher l'erreur
    end
```

Produit ce diagramme :

Les diagrammes de séquence sont excellents pour les articles sur les API. Ils montrent non seulement quels composants existent, mais aussi comment ils communiquent entre eux.

Syntaxe des diagrammes de classes

Les diagrammes de classes sont utiles pour les modèles de domaine et les relations entre objets.

ce code :

```mermaid
classDiagram
    class Utilisateur {
        +string id
        +string email
        +connexion()
        +déconnexion()
    }

    class Commande {
        +string id
        +float total
        +soumettre()
    }

    Utilisateur "1" --> "*" Commande
```

Produit ce diagramme :

Relations de classes

<|-- héritage
*-- composition
o-- agrégation
--> association
-- lien
..> dépendance
..|> réalisation

Exemple :

ce code :

```mermaid
classDiagram
    Animal <|-- Chien
    Animal <|-- Chat
    Utilisateur "1" --> "*" Commande
    Commande *-- LigneCommande
```

Produit ce diagramme :

Les diagrammes de classes peuvent devenir bruyants rapidement. Dans un article de blog, privilégiez une petite tranche de domaine plutôt qu’un modèle d’application complet.

Syntaxe des diagrammes d’état

Les diagrammes d’état expliquent comment quelque chose change au fil du temps.

ce code :

```mermaid
stateDiagram-v2
    [*] --> Brouillon
    Brouillon --> Relecture : soumettre
    Relecture --> Publié : approuver
    Relecture --> Brouillon : demander des modifications
    Publié --> Archivé : archiver
    Archivé --> [*]
```

Produit ce diagramme :

Utilisez les diagrammes d’état pour :

• Les cycles de vie des commandes
• Les états de déploiement
• Les flux d’authentification
• Le statut des tâches en arrière-plan
• Les flux de publication de contenu

Les diagrammes d’état sont sous-estimés. Ils expliquent souvent la logique métier mieux qu’un long paragraphe.

Syntaxe des diagrammes entité-association

Les diagrammes entité-association sont utiles pour les modèles de bases de données.

ce code :

```mermaid
erDiagram
    UTILISATEUR ||--o{ COMMANDE : place
    COMMANDE ||--|{ LIGNE_COMMANDE : contient
    PRODUIT ||--o{ LIGNE_COMMANDE : apparaît_dans

    UTILISATEUR {
        string id
        string email
    }

    COMMANDE {
        string id
        datetime créé_le
    }

    PRODUIT {
        string id
        string nom
    }
```

Produit ce diagramme :

Marqueurs de relation ER

||  exactement un
o|  zéro ou un
}|  un ou plusieurs
}o  zéro ou plusieurs

Les diagrammes ER sont meilleurs lorsqu’ils expliquent les relations, pas chaque colonne. Gardez les détails d’implémentation dans les migrations ou la documentation du schéma.

Syntaxe des diagrammes de Gantt

Les diagrammes de Gantt sont utiles pour les calendriers de projet.

ce code :

```mermaid
gantt
    titre Plan de migration de la documentation
    dateFormat  AAAA-MM-JJ

    section Planification
    Auditer les docs actuelles      :a1, 2026-06-01, 5j
    Définir la structure            :a2, après a1, 3j

    section Rédaction
    Réécrire les guides             :b1, après a2, 10j
    Relecture et publication        :b2, après b1, 4j
```

Produit ce diagramme :

Les diagrammes de Gantt sont utiles dans les posts de planification interne, mais ils peuvent vieillir rapidement. Utilisez-les lorsque le calendrier lui-même est l’objectif principal.

Syntaxe des frises chronologiques

Les frises chronologiques conviennent aux historiques de versions, rapports d’incidents et résumés de projet.

ce code :

```mermaid
timeline
    titre Évolution de l'API
    2024 : Lancement de l'API REST
    2025 : Ajout des Webhooks
    2026 : Introduction du streaming d'événements
```

Produit ce diagramme :

Utilisez une frise chronologique lorsque l’ordre est plus important que la dépendance. Si ce qui vous importe est la séquence des événements plutôt que leur connexion causale, une frise chronologique maintient le focus là où il doit être et reste facile à lire en un coup d’œil.

Syntaxe des diagrammes en camembert

Les diagrammes en camembert sont pris en charge, mais soyez prudent. Ils sont faciles à lire lorsqu’il n’y a que quelques catégories et que les valeurs sont clairement différentes.

ce code :

```mermaid
pie title Temps de construction par étape
    "Installer les dépendances" : 35
    "Exécuter les tests" : 45
    "Construire les actifs" : 20
```

Produit ce diagramme :

Conseil avisé : si les valeurs sont proches ou s’il y a plus de cinq catégories, utilisez un tableau à la place. Un tableau bien formaté communique des nombres précis plus honnêtement qu’un camembert où les tranches se ressemblent presque.

Syntaxe des graphes Git

Les graphes Git peuvent expliquer les stratégies de branchement et les flux de publication.

ce code :

```mermaid
gitGraph
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout main
    merge feature
    commit
```

Produit ce diagramme :

Cela est utile pour les articles sur les flux de travail Git, le développement basé sur le tronc (trunk-based), les branches de publication et les correctifs d’urgence (hotfixes). Si vous avez besoin d’une référence rapide des commandes de branchement sous-jacentes, la Fiche de référence GIT couvre les plus courantes aux côtés des flux de fusion et de rebase.

Fiche de référence Mermaid

Types de diagrammes

flowchart TD
sequenceDiagram
classDiagram
stateDiagram-v2
erDiagram
gantt
timeline
pie
gitGraph
mindmap
journey

Bases des organigrammes

flowchart TD
A[Texte] --> B[Texte]
A -->|Étiquette| B
A -.-> B
A ==> B
A --- B

Formes des organigrammes

A[Rectangle]
A(Arrondi)
A{Décision}
A((Cercle))
A[(Base de données)]
A[[Sous-routine]]
A>Drapeau]

Bases des diagrammes de séquence

sequenceDiagram
participant A
participant B
A->>B: Message
B-->>A: Réponse
activate B
deactivate B

Blocs de séquence

alt condition
else autre condition
end

opt étape optionnelle
end

loop chaque élément
end

par tâche parallèle
and autre tâche
end

Bases des diagrammes de classes

classDiagram
class Utilisateur
class Commande
Utilisateur --> Commande
Utilisateur "1" --> "*" Commande

Bases des diagrammes d’état

stateDiagram-v2
[*] --> Inactif
Inactif --> En cours
En cours --> Terminé
Terminé --> [*]

Bases des diagrammes ER

erDiagram
UTILISATEUR ||--o{ COMMANDE : place
COMMANDE ||--|{ LIGNE_COMMANDE : contient

Commentaires

Mermaid prend en charge les commentaires avec %%.

ce code :

```mermaid
flowchart TD
    %% Ceci est un commentaire
    A --> B
```

Produit ce diagramme :

Utilisation de Mermaid dans Hugo

Le contenu Hugo est généralement écrit en Markdown, donc Mermaid s’intègre naturellement dans un blog technique basé sur Hugo. La configuration exacte dépend de votre thème et de votre configuration de rendu Markdown.

Le modèle d’auteurage courant reste le même :

```mermaid
flowchart LR
    Markdown --> Hugo
    Hugo --> HTML
    HTML --> Navigateur
```

Si votre thème Hugo prend déjà en charge Mermaid, cela peut se rendre sans travail supplémentaire. Si ce n’est pas le cas, vous avez généralement besoin d’un hook de rendu, d’un shortcode, d’un partial ou d’une configuration de thème qui charge Mermaid sur les pages contenant des diagrammes Mermaid.

Une configuration Hugo pratique devrait viser ces règles :

• Garder la source Mermaid à l’intérieur des articles Markdown normaux.
• Charger Mermaid uniquement sur les pages qui en ont besoin.
• Éviter JavaScript global si la plupart des pages n’utilisent pas de diagrammes.
• Tester les diagrammes lors de la prévisualisation locale.
• Garder la source du diagramme lisible dans Git.

Pour un blog technique, les blocs de code clôturés sont généralement meilleurs que les shortcodes personnalisés car ils sont plus portables. Si vous déplacez plus tard le contenu vers GitHub, un autre générateur de site statique ou une plateforme de documentation, les blocs Mermaid clôturés standards sont plus faciles à réutiliser.

Bonnes pratiques Mermaid

Garder les diagrammes petits

Un diagramme doit clarifier l’article, pas le remplacer. Si les lecteurs doivent zoomer, le diagramme est probablement trop grand.

Les bons diagrammes ont généralement :

• Une seule idée
• Une direction claire
• Des étiquettes courtes
• Peu de lignes croisées
• Une nomenclature cohérente

Privilégier plusieurs petits diagrammes

Au lieu d’un énorme diagramme système, utilisez plusieurs diagrammes ciblés :

• Flux de requête
• Topologie de déploiement
• Modèle de données
• Cycle de vie d’état
• Chemin de défaillance

C’est meilleur pour les lecteurs et meilleur pour les écrans mobiles.

Utiliser des noms stables

Utilisez des noms qui correspondent à votre code, API ou documentation. Ne nommez pas la même chose API, Backend et Serveur dans différents diagrammes à moins qu’il ne s’agisse vraiment de concepts différents.

Étiqueter les flèches importantes

Les flèches sans étiquette conviennent aux organigrammes simples. Dans les diagrammes système, les étiquettes ont souvent de l’importance.

ce code :

```mermaid
flowchart LR
    Web -->|Requête HTTPS| API
    API -->|Requête SQL| BD
    API -->|Publier événement| File
```

Produit ce diagramme :

Éviter la syntaxe astucieuse

Mermaid peut faire beaucoup de choses. Cela ne signifie pas que chaque article doit les utiliser. Favorisez une syntaxe qu’un futur mainteneur peut comprendre rapidement.

Mettre les étiquettes entre guillemets si nécessaire

Si une étiquette contient des caractères qui dérangent Mermaid, entourez-la de guillemets.

ce code :

```mermaid
flowchart TD
    A["L'utilisateur clique /checkout"] --> B["POST /api/orders"]
```

Produit ce diagramme :

C’est une petite habitude qui empêche les échecs de rendu ennuyeux.

Penser au mode sombre

De nombreux sites Hugo prennent en charge le mode sombre. Assurez-vous que votre thème Mermaid ou votre CSS de site garde les diagrammes lisibles à la fois en mode clair et en mode sombre.

Erreurs courantes avec Mermaid

Erreur 1 : Trop de détails

Les mauvais diagrammes Mermaid essaient souvent de montrer chaque cas extrême. Cela les rend techniquement complets mais pratiquement illisibles. La solution est presque toujours la même : diviser le diagramme en deux ou trois plus petits, chacun couvrant une préoccupation, afin que les lecteurs puissent suivre la logique sans avoir à tracer une douzaine de flèches croisées.

Erreur 2 : Étiquettes longues

Les étiquettes longues créent des boîtes larges et des mises en page disgracieuses.

Au lieu de ce code :

```mermaid
flowchart TD
    A[L'utilisateur soumet le formulaire d'inscription avec son adresse e-mail et son mot de passe]
```

Produit ce diagramme :

Préférez ce code :

```mermaid
flowchart TD
    A[Soumettre le formulaire d'inscription]
```

Produit ce diagramme :

Expliquez les détails dans le paragraphe sous le diagramme.

Erreur 3 : Direction floue

Choisissez une direction et tenez-vous-y. La plupart des diagrammes de processus devraient utiliser TD. La plupart des diagrammes d’architecture sont plus faciles avec LR.

Erreur 4 : Traiter Mermaid comme un outil de design

Mermaid n’est pas Figma. Il n’est pas conçu pour des diagrammes parfaits au pixel près, et essayer de le forcer dans ce rôle ne conduira qu’à la frustration. Sa force réside dans sa maintenabilité, pas dans la perfection visuelle — et ce compromis est intentionnel.

Conseils SEO Mermaid pour les blogs techniques

Les diagrammes Mermaid peuvent rendre les articles techniques plus utiles, mais les moteurs de recherche ont toujours besoin de texte. Ne comptez pas uniquement sur les diagrammes.

Pour des articles Mermaid optimisés pour le SEO :

• Utilisez des titres H2 et H3 descriptifs.
• Expliquez chaque diagramme dans le texte voisin.
• Incluez les mots-clés importants dans le texte normal.
• Gardez les exemples de code copiables.
• Ajoutez une explication de style « alt » sous les diagrammes complexes.
• Utilisez un titre et une description front matter concis.
• Évitez de cacher tout le sens à l’intérieur du SVG rendu.

Un diagramme Mermaid doit soutenir l’article. Il ne devrait pas être le seul endroit où l’information importante existe.

Exemples Mermaid à copier-coller

Flux de requête API

ce code :

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Auth
    participant BD

    Client->>API: GET /account
    API->>Auth: Valider le jeton
    Auth-->>API: Jeton valide
    API->>BD: Charger le compte
    BD-->>API: Données du compte
    API-->>Client: 200 OK
```

Produit ce diagramme :

Pipeline CI

ce code :

```mermaid
flowchart TD
    A[Pousser le commit] --> B[Installer les dépendances]
    B --> C[Exécuter le linter]
    C --> D[Exécuter les tests]
    D --> E[Construire le site]
    E --> F[Déployer]
```

Produit ce diagramme :

Ce modèle s’adapte naturellement à une configuration CI réelle. Pour la syntaxe étape par étape des workflows GitHub Actions, la Fiche de référence GitHub Actions est un compagnon pratique lorsque vous souhaitez transformer le diagramme ci-dessus en un pipeline fonctionnel.

Flux de publication

ce code :

```mermaid
stateDiagram-v2
    [*] --> Brouillon
    Brouillon --> Édition
    Édition --> Relecture
    Relecture --> Publié
    Relecture --> Édition
    Publié --> [*]
```

Produit ce diagramme :

Modèle de données simple

ce code :

```mermaid
erDiagram
    AUTEUR ||--o{ ARTICLE : écrit
    ARTICLE ||--o{ COMMENTAIRE : reçoit

    AUTEUR {
        string id
        string nom
    }

    ARTICLE {
        string id
        string titre
        datetime publié_le
    }

    COMMENTAIRE {
        string id
        string corps
    }
```

Produit ce diagramme :

Quand ne pas utiliser Mermaid

N’utilisez pas Mermaid lorsque :

• Le diagramme nécessite une mise en page visuelle précise.
• Le design doit correspondre exactement à un système de marque.
• Le visuel est principalement décoratif.
• Le diagramme a trop de nœuds pour être lu.
• Une capture d’écran expliquerait le point mieux.
• Le contenu change rarement et a besoin de polish plutôt que de maintenabilité.

Mermaid est excellent pour la documentation technique vivante. Il est moins bon pour les œuvres d’art de qualité présentation. Pour des diagrammes de qualité document dans des contextes d’impression ou PDF, LaTeX offre des packages comme TikZ et pgfplots qui vous donnent un contrôle de mise en page bien supérieur — la Fiche de référence LaTeX couvre l’inclusion de diagrammes aux côtés du reste de la boîte à outils LaTeX.

Pensées finales

Mermaid est l’un des meilleurs outils pour le blogging technique car il respecte la façon dont les développeurs travaillent déjà : fichiers texte, Markdown, Git, revue de code et constructions reproductibles. Pour tout ce qui entoure les diagrammes — titres, listes, tableaux, blocs de code — la Fiche de référence Markdown est le compagnon de référence rapide à conserver aux côtés de ce guide.

Les meilleurs diagrammes Mermaid ne sont pas les plus complexes. Ce sont les diagrammes qui rendent un concept évident et restent faciles à éditer six mois plus tard.

Utilisez Mermaid pour les diagrammes qui devraient vivre avec votre documentation. Gardez-les petits, gardez-les lisibles, et traitez-les comme faisant partie du code source de votre article.