Diagrammes Mermaid pour les sites Jekyll

Les diagrammes Mermaid sont activés avec un seul indicateur de front matter et un bloc de code standard : aucun plugin côté serveur ni dépendance CDN, car le moteur de rendu est fourni avec le thème.

Compatible GitHub Pages — Fonctionne sans plugins personnalisés côté serveur !

Ce que vous allez faire : transformer un bloc de code ` ```mermaid ` en un diagramme rendu, zoomable, qui suit le mode couleur et le skin de votre site.

Prérequis :

• Une page construite avec ce thème (n’importe quelle mise en page)
• Une définition Mermaid — essayez-en une d’abord dans le Live Editor

Chaque diagramme d’une page est rendu sous forme de figure avec sa propre barre d’outils. Survolez le diagramme ci-dessous (ou touchez-le sur un téléphone) pour voir les contrôles :

flowchart TD
    accTitle: Choose an install path
    accDescr: Decision flowchart from "What's your goal?" to the six install options.
    A([Start]) --> B{What's your goal?}
    B --> C[New site, local dev]
    B --> D[Personal GitHub Pages site]
    B --> E[Add theme to existing repo]
    B --> F[Zero-install / cloud]
    C --> C1["Install wizard\ncurl … | bash + docker-compose up"]
    C --> C2["GitHub Template\ngh repo create --template"]
    D --> D1["Fork / clone\ngh repo fork + fork-cleanup.sh"]
    E --> E1["Remote theme\nremote_theme: bamr87/zer0-mistakes"]
    E --> E2["Ruby gem\ngem 'jekyll-theme-zer0'"]
    F --> F1["Codespaces\nOne click, browser-based"]

La légende sous le diagramme provient de sa ligne accTitle — voir Légendes et noms accessibles.

Démarrage rapide

Étape 1 : Activer Mermaid sur votre page

Ajoutez mermaid: true au front matter de votre page :

---
title: "My Documentation Page"
mermaid: true
---

Étape 2 : Écrire votre diagramme

Utilisez des blocs de code Markdown natifs avec mermaid comme langage :

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Try Again]
```

C’est tout ! Le diagramme est rendu automatiquement.

Vérifier

Rechargez la page. Le bloc de code est remplacé par une figure bordée contenant le diagramme ; le survol révèle la barre d’outils dans le coin supérieur droit. Si vous voyez toujours le texte brut, consultez la section Dépannage.

Ce dont bénéficie chaque diagramme

Chaque ` ```mermaid ` block becomes a <figure> avec un SVG rendu et une petite barre d’outils. Rien de plus à écrire — c’est le même bloc que vous écririez pour GitHub.

La barre d’outils

La barre d’outils apparaît au survol ou au focus clavier sur ordinateur, et se place au-dessus du diagramme sur les appareils tactiles.

Raccourcis clavier

Tabulez jusqu’à un diagramme (son cadre est focalisable, et aussi défilable), puis :

Légendes et noms accessibles

Les directives d’accessibilité de Mermaid servent à la fois de légende de la figure et de nom pour les lecteurs d’écran :

```mermaid
flowchart LR
    accTitle: How a fence becomes a figure
    accDescr: The theme converts a mermaid code fence into a figure and renders it.
    A["Mermaid code fence"] --> B["mermaid-diagrams.js"]
    B --> C{Parse OK?}
    C -- yes --> D["SVG figure + toolbar"]
    C -- no --> E["Error card + source"]
```

flowchart LR
    accTitle: How a fence becomes a figure
    accDescr: The theme converts a mermaid code fence into a figure and renders it.
    A["Mermaid code fence"] --> B["mermaid-diagrams.js"]
    B --> C{Parse OK?}
    C -- yes --> D["SVG figure + toolbar"]
    C -- no --> E["Error card + source"]

• accTitle devient la légende visible et le nom accessible du cadre du diagramme (le aria-label sur la région défilable) ; Mermaid l’inscrit également dans le <title> du SVG.
• accDescr est transmis au moteur de rendu de Mermaid, qui l’insère en tant que <desc> du SVG, lu par les lecteurs d’écran.
• Sans accTitle, le diagramme est nommé selon son type (« Organigramme », « Diagramme de séquence », …).

Les couleurs suivent votre thème

Les couleurs des diagrammes ne sont configurées nulle part. Elles sont dérivées au moment du rendu à partir des design tokens du thème (--bs-primary, --bs-body-bg, --zer0-color-*), de sorte qu’un diagramme correspond à ce que le lecteur regarde : mode clair ou sombre, n’importe quel skin, et n’importe quelle surcharge theme_color. Changez le mode couleur avec le bouton de la barre de navigation et regardez le diagramme ci-dessus se réafficher.

Le style par nœud (classDef, style) fonctionne toujours — le thème ne surcharge plus les couleurs SVG avec !important.

Quand un diagramme comporte une faute de frappe

Une erreur de syntaxe ne vide pas la page ni ne déverse de texte SVG brut. La figure indique ce qui n’a pas fonctionné et garde la source visible, et le contrôle Copier fonctionne toujours pour que vous puissiez la coller directement dans le Live Editor. Le diagramme ci-dessous est intentionnellement cassé (un seul -> là où Mermaid a besoin de -->) :

graph TD
    A[Start] -> B[Broken arrow]

Sans JavaScript

Le bundle Mermaid intégré et le script du thème se chargent tous deux avec defer, de sorte qu’ils ne bloquent jamais la page. Si JavaScript n’est pas disponible, ou si le script ne parvient pas à se charger, le bloc reste un bloc de code normal et lisible — la définition n’est jamais masquée.

Configuration

Configuration du site

Tout ce qui se trouve sous mermaid: dans _config.yml est optionnel :

mermaid:
  src: '/assets/vendor/mermaid/mermaid.min.js'   # vendored, no CDN
  security_level: strict   # strict | loose
  toolbar: true            # zoom / fullscreen / copy / download controls
  fullscreen: true         # allow the fullscreen view
  download: true           # allow "Download as SVG"

Les étiquettes de la barre d’outils sont traduites avec le reste de l’interface via _data/ui-text.yml (clés diagram_*).

Consultez Assets Bootstrap et icônes intégrés pour le workflow complet d’actualisation des assets.

Comment ça fonctionne

1. Indicateur de front matter — mermaid: true active Mermaid sur la page
2. Chargement conditionnel — les scripts ne se chargent que sur les pages qui l’activent, et ne bloquent jamais le rendu
3. Rendu côté client — aucun plugin côté serveur requis
4. Habillage de figure — assets/js/mermaid-diagrams.js convertit chaque bloc en figure, l’affiche, et le réaffiche lorsque le mode de couleur ou l’habillage change

Types de diagrammes

1. Organigrammes

Le type de diagramme le plus courant pour documenter les processus et les workflows.

Directions :

• TD / TB — De haut en bas
• BT — De bas en haut
• LR — De gauche à droite
• RL — De droite à gauche

```mermaid
graph LR
    A[Input] --> B[Process]
    B --> C{Valid?}
    C -->|Yes| D[Success]
    C -->|No| E[Error]
```

graph LR
    A[Input] --> B[Process]
    B --> C{Valid?}
    C -->|Yes| D[Success]
    C -->|No| E[Error]

Formes de nœuds :

Types de liens :

2. Diagrammes de séquence

Parfaits pour documenter les appels d’API, les interactions utilisateur et la communication système.

```mermaid
sequenceDiagram
    participant User
    participant Browser
    participant Server

    User->>Browser: Click button
    Browser->>Server: API request
    Note over Server: Validate + query
    Server-->>Browser: JSON response
    Browser-->>User: Display result
```

sequenceDiagram
    participant User
    participant Browser
    participant Server

    User->>Browser: Click button
    Browser->>Server: API request
    Note over Server: Validate + query
    Server-->>Browser: JSON response
    Browser-->>User: Display result

Types de flèches :

3. Diagrammes de classes

Documentez l’architecture du code et les relations.

```mermaid
classDiagram
    class JekyllSite {
        +String title
        +Array pages
        +build()
        +serve()
    }

    class Page {
        +String content
        +Hash frontMatter
        +render()
    }

    JekyllSite --> Page : contains
```

classDiagram
    class JekyllSite {
        +String title
        +Array pages
        +build()
        +serve()
    }

    class Page {
        +String content
        +Hash frontMatter
        +render()
    }

    JekyllSite --> Page : contains

4. Diagrammes d’états

Modélisez les machines à états et les workflows.

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review : Submit
    Review --> Published : Approve
    Review --> Draft : Reject
    Published --> [*]
```

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : Submit
    Review --> Published : Approve
    Review --> Draft : Reject
    Published --> [*]

5. Diagrammes entité-association

Documentez les schémas de base de données.

```mermaid
erDiagram
    POST ||--o{ TAG : has
    POST {
        string title
        string content
        date published_at
    }
    TAG {
        string name
        string slug
    }
```

erDiagram
    POST ||--o{ TAG : has
    POST {
        string title
        string content
        date published_at
    }
    TAG {
        string name
        string slug
    }

6. Diagrammes circulaires

Visualisez les distributions de données.

```mermaid
pie title Page Views by Section
    "Blog" : 45
    "Docs" : 30
    "Tutorials" : 15
    "About" : 10
```

pie title Page Views by Section
    "Blog" : 45
    "Docs" : 30
    "Tutorials" : 15
    "About" : 10

7. Diagrammes de Gantt

Chronologies et calendriers de projet.

```mermaid
gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    section Phase 1
    Research        :a1, 2026-01-01, 30d
    Design          :a2, after a1, 20d
    section Phase 2
    Development     :a3, after a2, 45d
    Testing         :a4, after a3, 15d
```

Une version plus riche illustre les balises de statut et le formatage des axes :

gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    axisFormat  %b %d
    tickInterval 2week
    section Phase 1
    Research        :done, a1, 2026-01-01, 30d
    Design          :active, a2, after a1, 20d
    section Phase 2
    Development     :a3, after a2, 45d
    Testing         :crit, a4, after a3, 15d

Les balises done, active et crit reprennent les couleurs discrète, d’accentuation et de danger du thème ; axisFormat et tickInterval évitent que les étiquettes d’axe se chevauchent sur les écrans étroits.

8. Graphes Git

Visualisez les branches et les commits Git.

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

gitGraph
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout main
    merge feature
    commit

Options de syntaxe

Option A : Markdown natif (recommandé)

Utilisez des blocs de code délimités — la solution la plus propre et la plus portable :

```mermaid
graph TD
    A --> B
```

Option B : div HTML

Utilisez <div class="mermaid"> — fonctionne lorsque le Markdown ne convient pas :

<div class="mermaid">
graph TD
    A --> B
</div>

Quand utiliser chacune

Les deux formes produisent la même figure, la même barre d’outils et le même thème.

Styles et thèmes

Application automatique du thème

Vous ne choisissez pas de thème Mermaid. Le thème utilise le thème base de Mermaid et remplit ses variables à partir des jetons de design en direct du site, de sorte que :

• Les modes de couleur clair / sombre / wizard disposent chacun d’une palette lisible, et un changement de mode réaffiche chaque diagramme sur place.
• Les habillages (data-theme-skin) recolorent les bordures, les remplissages des nœuds et les couleurs de série selon la marque de l’habillage.
• Les remplacements theme_color dans _config.yml transitent par les mêmes jetons.
• Les couleurs de série des parts de camembert, des branches git et des cartes mentales se déploient à partir de la teinte de la marque, afin de rester distinctes dans les deux modes.

Remplacer un diagramme unique

Une directive Mermaid en tête de bloc prime toujours pour ce diagramme — utile lorsqu’un graphique précis nécessite un rendu précis :

```mermaid
%%{init: {'theme': 'forest'}}%%
graph LR
    A --> B
```

Le style par nœud fonctionne comme documenté par Mermaid :

```mermaid
graph LR
    A[Normal] --> B[Highlighted]
    classDef hot fill:#fde68a,stroke:#b45309,color:#1f2937
    class B hot
```

graph LR
    A[Normal] --> B[Highlighted]
    classDef hot fill:#fde68a,stroke:#b45309,color:#1f2937
    class B hot

API JavaScript

Le composant expose une petite API pour les pages qui injectent du contenu après le chargement (onglets, résultats de recherche, chat IA) :

// Convert and render any new ```mermaid fences under a root element
window.zer0Mermaid.renderAll(document.querySelector('#tab-pane'));

// Re-derive the palette and re-render everything (after changing tokens)
window.zer0Mermaid.refresh();

// Render one element (a <pre>, <div class="mermaid">, or existing figure)
window.zer0Mermaid.render(element, 'graph TD; A --> B');

// Read a figure's source, or open it fullscreen
window.zer0Mermaid.getSource(figure);
window.zer0Mermaid.openFullscreen(figure);

Événements : zer0:diagram-rendered se déclenche sur chaque figure (detail.ok, detail.type, detail.error) ; zer0:diagrams-ready se déclenche sur document une fois un lot terminé (detail.count, detail.failed).

Dépannage

Le diagramme ne s’affiche pas

Erreurs de syntaxe courantes

Wrong: graph TD A -> B      (single arrow)
Right: graph TD A --> B     (double arrow)

Wrong: graph TD A[Text]B    (no arrow between nodes)
Right: graph TD A[Text] --> B

graph TD et flowchart TD sont équivalents : flowchart est le mot-clé actuel, graph un alias hérité que Mermaid accepte encore.

Tester en local

# Start Jekyll dev server
docker-compose up

# Check browser console for errors
# Open http://localhost:4000/your-page

Accessibilité

• Chaque diagramme est un <figure> ; accTitle devient son <figcaption> et son nom accessible.
• Le cadre du diagramme est une région focalisable et pilotable au clavier (voir les raccourcis), de sorte qu’un diagramme plus large que la page n’est jamais piégé derrière un défilement à la souris uniquement.
• Les boutons de la barre d’outils sont de véritables <button> avec des libellés ; le niveau de zoom et le retour de copie sont annoncés via une région live discrète.
• La vue plein écran est un <dialog> natif : le focus y est piégé, Esc la ferme, et le focus revient au contrôle qui l’a ouverte.
• Les couleurs de série sont choisies à une luminosité fixe par mode de couleur, afin que les parts de camembert et les branches adjacentes restent distinguables.

Bonnes pratiques

1. N’activez que si nécessaire — utilisez mermaid: true uniquement sur les pages comportant des diagrammes
2. Donnez un accTitle aux diagrammes — c’est la légende, le nom accessible et le nom de fichier d’un export SVG
3. Gardez les diagrammes simples — les diagrammes complexes ralentissent le rendu
4. Testez dans l’éditeur en direct — utilisez d’abord mermaid.live
5. Ajoutez des descriptions — les diagrammes complexes nécessitent des explications textuelles
6. Utilisez des libellés clairs — évitez les abréviations

Ressources

• Documentation Mermaid : mermaid.js.org
• Éditeur en direct : mermaid.live
• Référence de syntaxe : Syntaxe Mermaid
• Directives d’accessibilité : Accessibilité Mermaid
• Configuration du thème : Thème Mermaid

Référence technique

Pour les détails d’implémentation (modifications de fichiers, suite de tests) :

• Intégration Mermaid v2.0 → docs/implementation/feature-change-log.md — décrit l’approche antérieure <div class="mermaid"> ; la refonte actuelle des figures, de la barre d’outils et du thème par tokens est enregistrée sous ZER0-013 dans _data/features.yml
• Fichiers de composants : _includes/components/mermaid.html (chargeur), assets/js/mermaid-diagrams.js (comportement), _sass/components/_mermaid.scss (styles)
• Test de régression : test/visual/features/mermaid.spec.js

Voir aussi

• [[Features]]
• [[MathJax Math]]
• [[Jupyter Notebook Integration]]