Diagrammes Mermaid

Créez des organigrammes, des diagrammes de séquence, des diagrammes de classes et bien plus dans votre site Jekyll grâce à la syntaxe textuelle simple de Mermaid.

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

Un bloc ` ```mermaid ` est rendu sous forme de diagramme SVG dans le navigateur. Par exemple, l’organigramme « choisissez votre parcours » du guide de démarrage rapide est un bloc Mermaid que le thème rend automatiquement :

Démarrage rapide

Étape 1 : Activer Mermaid sur votre page

Ajoutez mermaid: true dans le 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.

Configuration

Configuration du site

Le thème intègre la prise en charge de Mermaid dans _config.yml :

mermaid:
  src: '/assets/vendor/mermaid/mermaid.min.js'

Comment ça fonctionne

1. Indicateur du front matter — mermaid: true active Mermaid sur la page
2. Chargement conditionnel — Le script ne se charge que lorsque c’est nécessaire
3. Rendu côté client — Aucun plugin côté serveur requis
4. Initialisation automatique — Les diagrammes sont rendus au chargement de la page

Types de diagrammes

1. Organigrammes

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

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]
```

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 entre systèmes.

```mermaid
sequenceDiagram
    participant User
    participant Browser
    participant Server
    
    User->>Browser: Click button
    Browser->>Server: API request
    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
```

4. Diagrammes d’états

Modélisez les machines à états et les flux de travail.

```mermaid
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
    }
```

6. Diagrammes circulaires

Visualisez les répartitions de données.

```mermaid
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
```

8. Graphiques Git

Visualisez les branches et les commits Git.

```mermaid
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 fonctionne pas :

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

Quand utiliser chacune

Styles et thèmes

Thèmes disponibles

Mermaid prend en charge plusieurs thèmes intégrés :

mermaid.initialize({
  theme: 'default'  // or 'forest', 'dark', 'neutral', 'base'
});

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

Wrong: flowchart TD         (in older Mermaid versions)
Right: graph TD             (more compatible)

Test en local

# Start Jekyll dev server
docker-compose up

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

Bonnes pratiques

1. N’activez que si nécessaire — utilisez mermaid: true uniquement sur les pages contenant des diagrammes
2. Gardez les diagrammes simples — les diagrammes complexes ralentissent le rendu
3. Testez dans l’éditeur en ligne — utilisez d’abord mermaid.live
4. Ajoutez des descriptions — les diagrammes complexes nécessitent des explications textuelles
5. Utilisez des libellés clairs — évitez les abréviations

Ressources

• Documentation Mermaid : mermaid.js.org
• Éditeur en ligne : mermaid.live
• Référence de syntaxe : Syntaxe Mermaid
• Configuration des thèmes : Thèmes Mermaid

Ce guide fait partie de la documentation du thème Jekyll Zer0-Mistakes.

Référence technique

Pour les détails d’implémentation (comment Mermaid v2 a été intégré, modifications de fichiers, suite de tests) :

• Intégration de Mermaid → docs/implementation/feature-change-log.md

Voir aussi

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