Diagrammes

Markdown permet de créer différents types de diagrammes et d'organigrammes grâce à la syntaxe Mermaid, offrant une expression visuelle à votre documentation.

Introduction à Mermaid

Mermaid est un outil de génération de diagrammes basé sur du texte qui prend en charge de nombreux types de diagrammes :

• Organigramme (Flowchart)
• Diagramme de séquence
• Diagramme de Gantt
• Diagramme de classes
• Diagramme d'états
• Diagramme circulaire (Pie Chart)
• Parcours utilisateur (User Journey)
• Graphe Git

Syntaxe de base

Organigramme (Flowchart)

```mermaid
flowchart TD
    A[Début] --> B{Connecté ?}
    B -->|Oui| C[Afficher Accueil]
    B -->|Non| D[Afficher Connexion]
    C --> E[Fin]
    D --> F[Connexion Utilisateur]
    F --> G{Connexion réussie ?}
    G -->|Oui| C
    G -->|Non| H[Afficher Erreur]
    H --> D

**Rendu obtenu :**

```mermaid
flowchart TD
    A[Début] --> B{Connecté ?}
    B -->|Oui| C[Afficher Accueil]
    B -->|Non| D[Afficher Connexion]
    C --> E[Fin]
    D --> F[Connexion Utilisateur]
    F --> G{Connexion réussie ?}
    G -->|Oui| C
    G -->|Non| H[Afficher Erreur]
    H --> D

Diagramme de séquence

```mermaid
sequenceDiagram
    participant Utilisateur
    participant Frontend
    participant Backend
    participant BaseDeDonnées
    
    Utilisateur->>Frontend: Requête de connexion
    Frontend->>Backend: Valider utilisateur
    Backend->>BaseDeDonnées: Requête données utilisateur
    BaseDeDonnées-->>Backend: Retour infos utilisateur
    Backend-->>Frontend: Résultat validation
    Frontend-->>Utilisateur: Réponse connexion

**Rendu obtenu :**

```mermaid
sequenceDiagram
    participant Utilisateur
    participant Frontend
    participant Backend
    participant BaseDeDonnées
    
    Utilisateur->>Frontend: Requête de connexion
    Frontend->>Backend: Valider utilisateur
    Backend->>BaseDeDonnées: Requête données utilisateur
    BaseDeDonnées-->>Backend: Retour infos utilisateur
    Backend-->>Frontend: Résultat validation
    Frontend-->>Utilisateur: Réponse connexion

Détails sur les organigrammes

Types de nœuds

```mermaid
flowchart LR
    A[Nœud rectangle]
    B(Nœud arrondi)
    C((Nœud cercle))
    D{Nœud losange}
    E[[Sous-routine]]
    F[(Base de données)]
    G>Étiquette]

**Rendu obtenu :**

```mermaid
flowchart LR
    A[Nœud rectangle]
    B(Nœud arrondi)
    C((Nœud cercle))
    D{Nœud losange}
    E[[Sous-routine]]
    F[(Base de données)]
    G>Étiquette]

Types d'arêtes

```mermaid
flowchart TD
    A --> B
    C --- D
    E -.-> F
    G ==> H
    I --o J
    K --x L

**Rendu obtenu :**

```mermaid
flowchart TD
    A --> B
    C --- D
    E -.-> F
    G ==> H
    I --o J
    K --x L

Contrôle de la direction

<!-- De haut en bas -->
```mermaid
flowchart TD
    A --> B

flowchart BT
    A --> B

flowchart LR
    A --> B

flowchart RL
    A --> B

### Exemple d'organigramme complexe

```markdown
```mermaid
flowchart TD
    Start([Début du projet]) --> Analyse[Analyse des besoins]
    Analyse --> Design[Conception système]
    Design --> Dev{Phase de développement}
    
    Dev --> Frontend[Dév. Frontend]
    Dev --> Backend[Dév. Backend]
    Dev --> Database[Conception BDD]
    
    Frontend --> FrontTest[Test Frontend]
    Backend --> BackTest[Test Backend]
    Database --> DataTest[Test Données]
    
    FrontTest --> Integration[Test d'intégration]
    BackTest --> Integration
    DataTest --> Integration
    
    Integration --> Deploy{Préparation déploiement}
    Deploy -->|Succès| Production[Production]
    Deploy -->|Échec| Bug[Correction]
    Bug --> Integration
    
    Production --> Monitor[Surveillance]
    Monitor --> End([Projet terminé])
    
    style Start fill:#e1f5fe
    style End fill:#e8f5e8
    style Bug fill:#ffebee

**Rendu obtenu :**

```mermaid
flowchart TD
    Start([Début du projet]) --> Analyse[Analyse des besoins]
    Analyse --> Design[Conception système]
    Design --> Dev{Phase de développement}
    
    Dev --> Frontend[Dév. Frontend]
    Dev --> Backend[Dév. Backend]
    Dev --> Database[Conception BDD]
    
    Frontend --> FrontTest[Test Frontend]
    Backend --> BackTest[Test Backend]
    Database --> DataTest[Test Données]
    
    FrontTest --> Integration[Test d'intégration]
    BackTest --> Integration
    DataTest --> Integration
    
    Integration --> Deploy{Préparation déploiement}
    Deploy -->|Succès| Production[Production]
    Deploy -->|Échec| Bug[Correction]
    Bug --> Integration
    
    Production --> Monitor[Surveillance]
    Monitor --> End([Projet terminé])
    
    style Start fill:#e1f5fe
    style End fill:#e8f5e8
    style Bug fill:#ffebee

Détails sur les diagrammes de séquence

Syntaxe de base

sequenceDiagram
    Alice->>Bob: Bonjour Bob, comment vas-tu ?
    Bob-->>Alice: Je vais bien, merci !
    Alice-)Bob: Au revoir !

Rendu obtenu :

sequenceDiagram
    Alice->>Bob: Bonjour Bob, comment vas-tu ?
    Bob-->>Alice: Je vais bien, merci !
    Alice-)Bob: Au revoir !

Barres d'activation et durées de vie

sequenceDiagram
    participant A as Client
    participant B as Serveur
    
    A->>+B: Demande de données
    Note right of B: Traitement de la demande
    B-->>-A: Retour des données
    
    A->>+B: Nouvelle demande
    B->>+B: Traitement interne
    B-->>-B: Traitement terminé
    B-->>-A: Retour du résultat

Rendu obtenu :

sequenceDiagram
    participant A as Client
    participant B as Serveur
    
    A->>+B: Demande de données
    Note right of B: Traitement de la demande
    B-->>-A: Retour des données
    
    A->>+B: Nouvelle demande
    B->>+B: Traitement interne
    B-->>-B: Traitement terminé
    B-->>-A: Retour du résultat

Boucles et conditions

sequenceDiagram
    participant U as Utilisateur
    participant S as Système
    
    U->>S: Requête de connexion
    
    alt Nom d'utilisateur existe
        S->>S: Valider le mot de passe
        alt Mot de passe correct
            S-->>U: Connexion réussie
        else Mot de passe incorrect
            S-->>U: Mauvais mot de passe
        end
    else Nom d'utilisateur introuvable
        S-->>U: Utilisateur non trouvé
    end
    
    opt Se souvenir de moi
        S->>S: Sauvegarder l'état de connexion
    end

Rendu obtenu :

sequenceDiagram
    participant U as Utilisateur
    participant S as Système
    
    U->>S: Requête de connexion
    
    alt Nom d'utilisateur existe
        S->>S: Valider le mot de passe
        alt Mot de passe correct
            S-->>U: Connexion réussie
        else Mot de passe incorrect
            S-->>U: Mauvais mot de passe
        end
    else Nom d'utilisateur introuvable
        S-->>U: Utilisateur non trouvé
    end
    
    opt Se souvenir de moi
        S->>S: Sauvegarder l'état de connexion
    end

Diagramme de classes

classDiagram
    class Animal {
        +String name
        +int age
        +eat()
        +sleep()
    }
    
    class Dog {
        +String breed
        +bark()
        +wagTail()
    }
    
    class Cat {
        +String color
        +meow()
        +purr()
    }
    
    Animal <|-- Dog
    Animal <|-- Cat
    
    class Owner {
        +String name
        +feedPet()
    }
    
    Owner --> Animal : owns

Rendu obtenu :

classDiagram
    class Animal {
        +String name
        +int age
        +eat()
        +sleep()
    }
    
    class Dog {
        +String breed
        +bark()
        +wagTail()
    }
    
    class Cat {
        +String color
        +meow()
        +purr()
    }
    
    Animal <|-- Dog
    Animal <|-- Cat
    
    class Owner {
        +String name
        +feedPet()
    }
    
    Owner --> Animal : owns

Diagramme d'états

stateDiagram-v2
    [*] --> Idle
    Idle --> Running : Start
    Running --> Paused : Pause
    Running --> Finished : End
    Paused --> Running : Resume
    Paused --> Stopped : Stop
    Stopped --> Idle : Reset
    Finished --> Idle : Reset
    Finished --> [*]
    
    state Running {
        [*] --> Init
        Init --> Processing
        Processing --> Validate
        Validate --> [*]
    }

Rendu obtenu :

stateDiagram-v2
    [*] --> Idle
    Idle --> Running : Start
    Running --> Paused : Pause
    Running --> Finished : End
    Paused --> Running : Resume
    Paused --> Stopped : Stop
    Stopped --> Idle : Reset
    Finished --> Idle : Reset
    Finished --> [*]
    
    state Running {
        [*] --> Init
        Init --> Processing
        Processing --> Validate
        Validate --> [*]
    }

Diagramme de Gantt

gantt
    title Project Development Timeline
    dateFormat  YYYY-MM-DD
    section Requirement Analysis
    Requirement Collection          :done,    des1, 2024-01-01,2024-01-05
    Requirement Analysis            :done,    des2, after des1, 5d
    Requirement Review              :done,    des3, after des2, 2d
    
    section Design Phase
    System Design                   :active,  design1, 2024-01-12, 7d
    UI Design                       :         design2, after design1, 5d
    Database Design                 :         design3, after design1, 3d
    
    section Development Phase
    Frontend Development            :         dev1, after design2, 10d
    Backend Development             :         dev2, after design3, 12d
    Testing                         :         test1, after dev1, 5d

Diagramme circulaire

pie title Website Traffic Sources
    "Search Engine" : 45
    "Social Media" : 25
    "Direct" : 20
    "Email Marketing" : 7
    "Other" : 3

Parcours utilisateur

journey
    title User Shopping Journey
    section Discovery
      Visit Homepage: 3: User
      Browse Products: 4: User
      Search Products: 4: User
    section Consideration
      View Details: 4: User
      Compare Prices: 3: User
      Read Reviews: 5: User
    section Purchase
      Add to Cart: 4: User
      Checkout: 3: User
      Pay: 2: User
    section Use
      Receive Product: 5: User
      Use Product: 4: User
      Write Review: 4: User

Graphe Git

gitgraph
    commit id: "Initial Commit"
    commit id: "Add User Module"
    branch feature/auth
    commit id: "Add Login Feature"
    commit id: "Add Register Feature"
    checkout main
    commit id: "Fix Home Bug"
    merge feature/auth
    commit id: "v1.0 Release"
    branch hotfix
    commit id: "Urgent Fix"
    checkout main
    merge hotfix
    commit id: "v1.0.1 Release"

Scénarios réels

Diagramme d'architecture système

flowchart TB
    subgraph "User Layer"
        Web[Web Browser]
        Mobile[Mobile App]
        API[API Client]
    end
    
    subgraph "Gateway Layer"
        Gateway[API Gateway]
        Auth[Auth Service]
    end
    
    subgraph "Service Layer"
        UserService[User Service]
        OrderService[Order Service]
        PaymentService[Payment Service]
        NotificationService[Notification Service]
    end
    
    subgraph "Data Layer"
        UserDB[(User DB)]
        OrderDB[(Order DB)]
        Cache[(Redis Cache)]
        Queue[Message Queue]
    end
    
    Web --> Gateway
    Mobile --> Gateway
    API --> Gateway
    
    Gateway --> Auth
    Gateway --> UserService
    Gateway --> OrderService
    Gateway --> PaymentService
    
    UserService --> UserDB
    OrderService --> OrderDB
    PaymentService --> Queue
    NotificationService --> Queue
    
    UserService --> Cache
    OrderService --> Cache
    
    style Gateway fill:#e1f5fe
    style Auth fill:#fff3e0
    style Cache fill:#f3e5f5

Flux d'appel d'API

sequenceDiagram
    participant C as Client
    participant G as API Gateway
    participant A as Auth Service
    participant U as User Service
    participant D as Database
    participant R as Redis
    
    C->>G: Request User Info
    G->>A: Validate Token
    A->>R: Check Token Cache
    R-->>A: Token Valid
    A-->>G: Auth Success
    
    G->>U: Get User Info
    U->>R: Check User Cache
    alt Cache Exists
        R-->>U: Return User Data
    else Cache Miss
        U->>D: Query Database
        D-->>U: Return User Info
        U->>R: Update Cache
    end
    
    U-->>G: Return User Info
    G-->>C: Respond User Data

Flux d'affaires

flowchart TD
    Start([User Order]) --> Check{Check Stock}
    Check -->|In Stock| Reserve[Reserve Stock]
    Check -->|Out of Stock| OutOfStock[Out of Stock]
    OutOfStock --> Notify[Notify User]
    Notify --> End1([End])
    
    Reserve --> Payment{Payment Processing}
    Payment -->|Success| ConfirmOrder[Confirm Order]
    Payment -->|Fail| ReleaseStock[Release Stock]
    ReleaseStock --> PaymentFailed[Payment Failed]
    PaymentFailed --> End2([End])
    
    ConfirmOrder --> UpdateInventory[Update Inventory]
    UpdateInventory --> SendNotification[Send Notification]
    SendNotification --> Logistics[Arrange Logistics]
    Logistics --> End3([Order Complete])
    
    style Start fill:#e8f5e8
    style End1 fill:#ffebee
    style End2 fill:#ffebee
    style End3 fill:#e8f5e8
    style OutOfStock fill:#ffebee
    style PaymentFailed fill:#ffebee

Styles et thèmes

Styles de nœuds

flowchart LR
    A[Style par défaut] --> B[Style 1]
    A --> C[Style 2]
    A --> D[Style 3]
    
    style B fill:#f9f,stroke:#333,stroke-width:4px
    style C fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
    style D fill:#f96,stroke:#333,stroke-width:4px,color:#fff

Styles de classes

flowchart LR
    A[Nœud A]:::classA --> B[Nœud B]:::classB
    A --> C[Nœud C]:::classC
    
    classDef classA fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef classB fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef classC fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px

Configuration et compatibilité

Configuration VitePress

// .vitepress/config.js
export default {
  markdown: {
    mermaid: true
  }
}

Support GitHub

GitHub prend en charge nativement Mermaid, vous pouvez l'utiliser directement dans les fichiers Markdown :

```mermaid
graph LR
    A --> B

### Support d'autres plateformes

| Plateforme      | Support      | Configuration requise |
|--------------|--------------|-------------------|
| **GitHub**   | ✅ Natif     | Aucune              |
| **GitLab**   | ✅ Natif     | Aucune              |
| **VitePress**| ✅ Plugin     | Configuration nécessaire      |
| **Jekyll**   | ✅ Plugin     | Installation du plugin    |
| **Hugo**     | ✅ Thème      | Dépend du thème  |

## Meilleures pratiques

### Conseils de conception

```markdown
✅ Recommandé :

1. **Gardez-le simple :**
   - Évitez les diagrammes trop complexes
   - Utilisez des étiquettes et des connexions claires

2. **Disposition logique :**
   - Choisissez le bon sens de direction
   - Gardez la logique de flux claire

3. **Style cohérent :**
   - Utilisez un thème de couleur cohérent
   - Gardez le style du diagramme uniforme

4. **Ajoutez des explications :**
   - Ajoutez des titres pour les diagrammes complexes
   - Fournissez des explications textuelles nécessaires

❌ Évitez :

1. Les diagrammes trop complexes à comprendre
2. Trop de lignes croisées
3. Étiquettes vagues
4. Légendes manquantes

Considérations de performance

- **Optimisation des diagrammes complexes :**
  - Considérez la division des diagrammes complexes
  - Utilisez des sous-graphes pour l'organisation

- **Performances de chargement :**
  - Évitez trop de diagrammes sur une seule page
  - Considérez le chargement paresseux

- **Adaptation mobile :**
  - Assurez-vous que les diagrammes sont lisibles sur les petits écrans
  - Considérez le défilement horizontal

Syntaxes liées

• Embed HTML - Améliorations HTML
• Formules mathématiques - Expressions LaTeX
• Meilleures pratiques - Conseils d'écriture

Outils et ressources

Éditeurs en ligne

• Mermaid Live Editor : Éditeur officiel en ligne
• Draw.io : Outil de diagramme général
• Lucidchart : Plateforme de diagramme professionnelle
• Excalidraw : Style de diagramme à main levée

Outils de développement

• Mermaid CLI : Outil en ligne de commande
• VS Code Mermaid : Extension Visual Studio Code
• Atom Mermaid : Extension d'éditeur Atom
• IntelliJ Mermaid : Extension IDE JetBrains

Références

• Documentation officielle Mermaid : Référence complète de la syntaxe
• Bibliothèque d'exemples Mermaid : Divers exemples de diagrammes
• GitHub Mermaid : Utilisation sur GitHub
• Awesome Mermaid : Collection de ressources

En maîtrisant la syntaxe des organigrammes, vous pouvez créer des diagrammes visuels professionnels dans votre documentation, améliorant la clarté et l'expressivité.