Diagrams Mermaid Architecture du document en Markdown sans cliquer sur rien

Votre diagramme d'architecture était précis lors de sa création. C'était il y a trois sprints. Maintenant, il est intégré dans une présentation Google partagée que personne ne met à jour, et l'ingénieur qui a construit le service qu'il décrit a quitté son équipe. Cela vous semble familier ?

Les diagrammes Mermaid inversent ce problème. Au lieu d'avoir un tableau de bord drag-and-drop situé en dehors de votre codebase, vous écrivez des diagrammes au format texte — une syntaxe Markdown simple qui se trouve dans votre README, est contrôlée par version avec votre code, et se rend au lieu où Markdown est affiché. Quand l'architecture change, vous modifiez un seul fichier texte. La différence raconte toute l'histoire.

Ce que Mermaid est (et pourquoi les diagrammes en code sont importants)

Mermaid est une langue ouverte de création de diagrammes qui génère des diagrammes à partir de texte brut. Vous écrivez un diagramme de flux dans un bloc de code ; un rendu (ou un lecteur Mermaid) le transforme en un diagramme SVG. Aucun compte, aucune étape d'exportation, aucun « le format de diagramme n'est pas pris en charge sur cette machine ».

L'approche « diagrammes en code » se justifie de plusieurs manières concrètes :

• Contrôle de version — les diagrammes sont présents dans Git. Vous pouvez les comparer, les annuler et les associer à la même demande de modification que le code qu'ils décrivent.
• Pas de dépendance à un fournisseur — le texte brut est portable. Vous pouvez changer le rendu, forker le dépôt, exporter vers Confluence — la source est toujours lisible.
• Proche du code — un diagramme dans le même dépôt que le service qu'il décrit est beaucoup plus susceptible de rester précis qu'un diagramme dans une présentation partagée.
• Adaptabilité aux automatisations — vous pouvez générer une syntaxe Mermaid à partir du code (schémas de base de données, spécifications API, pipelines CI) à l'aide de scripts ou d'IA.

Avant de passer à des types de diagrammes, vous pouvez visualiser instantanément n'importe quelle syntaxe Mermaid — sans installation locale — grâce à la Application de rendu Mermaid sur iotools.cloud. Collez, voyez le résultat, itérez. Utilisez-la en parallèle avec ce guide pour exécuter chaque exemple en temps réel.

Flux : le travailleur principal

Les diagrammes de flux sont le type de diagramme le plus courant de Mermaid, et pour une bonne raison — ils gèrent tout, de simples arbres de décision à des flux complexes entre plusieurs services. Voici la syntaxe qui couvre 90% de cas d'utilisation réels :

flowchart TD
    A[User submits form] --> B{Validation passes?}
    B -- Yes --> C[Save to database]
    B -- No --> D[Return error to client]
    C --> E[Send confirmation email]
    E --> F([End])

Quelques points à connaître sur la syntaxe des diagrammes de flux :

• Direction: TD (de haut en bas), LR (de gauche à droite), BT (de bas en haut), RL (de droite à gauche)
• Formes des nœuds: [rectangle], (rounded), ([stadium]), {diamond}, ((circle)), [(cylinder)]
• Étiquettes des arêtes: -- label --> ou -->|label|
• Sous-graphes: regroupe visuellement des nœuds liés

Les sous-graphes sont particulièrement utiles pour montrer les limites des services :

flowchart LR
    subgraph Frontend
        UI[React App]
    end
    subgraph Backend
        API[FastAPI]
        DB[(PostgreSQL)]
    end
    UI --> API
    API --> DB

Diagrammes de séquence : montrer les flux d'appels API

Les diagrammes de séquence sont l'outil idéal lorsque vous devez montrer l'ordre des interactions entre les systèmes — une chaîne d'appels API, un flux d'authentification, une séquence de webhook. Ils rendent clair le timing et la responsabilité d'une manière que les diagrammes de flux ne peuvent pas faire.

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Users DB

    Client->>API Gateway: POST /login {email, password}
    API Gateway->>Auth Service: Validate credentials
    Auth Service->>Users DB: SELECT user WHERE email=?
    Users DB-->>Auth Service: User record
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK {token}

Des flèches solides (->>) représentent les demandes ; des flèches pointillées (-->>) représentent les réponses. Les participant déclarations contrôlent l'ordre dans lequel les boîtes apparaissent au sommet du diagramme. Vous pouvez également utiliser actor pour les participants humains, activate/deactivate pour montrer le temps de traitement, et loop ou alt des blocs pour les flux conditionnels.

Diagrammes d'entité-association : schémas de bases de données dans les documents

Les diagrammes d'entité-association doivent être inclus dans chaque README d'un service qui possède un schéma de base de données. La syntaxe d'entité-association de Mermaid est propre et couvre la cardinalité par défaut :

erDiagram
    USER {
        int id PK
        string email
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

Notation de cardinalité : || est exactement une, o| est zéro ou une, o{ est zéro ou plusieurs, |{ est une ou plusieurs. L'étiquette de la relation (« lieux », « contient ») est placée entre guillemets à la fin.

Diagrammes d'état : modéliser les flux et les machines d'état

Quand vous avez un élément qui passe par des états distincts — une commande, une abonnement, un job CI — un diagramme d'état est plus précis qu'un diagramme de flux. La syntaxe de diagramme d'état de Mermaid correspond directement à la manière dont vous définiriez une machine d'état dans le code :

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing : payment received
    Processing --> Shipped : warehouse picks order
    Shipped --> Delivered : carrier confirms
    Shipped --> Returned : customer initiates return
    Delivered --> [*]
    Returned --> Refunded : refund processed
    Refunded --> [*]

[*] marque les états de départ et de fin. Les transitions portent l'événement qui les déclenche. Vous pouvez imbriquer des états pour des états composés et utiliser note des blocs pour annoter les transitions avec un contexte supplémentaire.

Diagrammes de classes : structures OOP pour les documents d'orientation

Les diagrammes de classes sont particulièrement utiles lors de l'orientation des ingénieurs sur un codebase orienté objet ou lors de la documentation d'un modèle de domaine. Mermaid couvre l'héritage, les interfaces, la composition et les signatures de méthodes :

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +boolean isIndoor
        +purr() void
    }
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends

Les modificateurs de visibilité suivent la convention UML : + public, - private, # protected. Les flèches de relation couvrent l'association (-->), l'héritage (<|--), la composition (*--), et l'agrégation (o--).

Où Mermaid se rend nativement

Le point fort réel de Mermaid est son support natif dans les outils que les développeurs utilisent déjà :

• GitHub — les blocs de code Mermaid (```mermaid) se rendent dans les README, les demandes, les descriptions de PR et les wikis à partir de 2022.
• GitLab — le support natif des fichiers Markdown et des pages wiki.
• Notion — collez un bloc de code Mermaid dans un bloc de code réglé sur « Mermaid » et il se rend en ligne.
• VS Code — l'extension de vision prévue Mermaid Support rend les diagrammes dans la fenêtre de prévisualisation intégrée.
• Obsidian — Mermaid se rend nativement sans aucun plugin.
• Docusaurus, MkDocs, Astro — des plugins Mermaid existent pour tous les générateurs de sites statiques principaux.
• Confluence — via l'application Mermaid Diagrams for Confluence.

Si vous écrivez des documents qui seront publiés sur GitHub ou GitLab, les diagrammes Mermaid fonctionnent sans configuration.

Les pièges et les cas où il faut utiliser autre chose

Mermaid n'est pas parfait pour chaque situation. Quelques points à surveiller :

• Layouts complexes — l'algorithme d'auto-layout de Mermaid ne produit pas toujours des résultats clairs pour de grands graphes. Si vous avez 50+ nœuds avec de nombreuses arêtes croisées, vous devrez peut-être réorganiser ou diviser manuellement les diagrammes.
• Rendu dans Confluence — Confluence ne supporte pas nativement Mermaid ; vous devez utiliser une application payante. Si votre équipe utilise Confluence, prévoyez un budget pour cela ou utilisez draw.io au lieu.
• Types de diagrammes non standardisés — les diagrammes de réseaux, les diagrammes de déploiement et les diagrammes C4 d'architecture nécessitent des contournements ou ne sont pas bien supportés.
• Contrôle de style — les options de personnalisation de Mermaid sont limitées. Pour des diagrammes marqués avec des couleurs et polices personnalisées, vous passerez du temps à lutter contre le rendu.

Les alternatives principales à connaître :

• PlantUML — syntaxe plus ancienne et plus verbeuse, mais un meilleur support UML et une meilleure intégration avec Confluence. Exige une installation locale Java ou un rendu serveur.
• D2 — outil récent de diagrammes en code avec un meilleur contrôle de layout et une meilleure gestion des grands diagrammes. Moins d'adoption dans l'écosystème que Mermaid, mais en croissance rapide.
• draw.io / Excalidraw — outils graphiques pour les cas où vous avez besoin de contrôle visuel précis et que vous n'êtes pas enclin à laisser le diagramme en dehors du contrôle de version.

Pour la plupart des documents de développeurs — les README des services, les flux API, les guides d'orientation — Mermaid couvre bien le cas d'usage, et le support natif de GitHub seul en fait une valeur ajoutée, même si le coût d'apprentissage est présent.

Aperçu de Mermaid sans installation

Si vous expérimentez avec la syntaxe ou souhaitez partager un diagramme avec quelqu'un qui n'a pas de rendu local installé, la Application de rendu Mermaid sur iotools.cloud vous donne une prévisualisation en temps réel sans inscription, sans installation et sans configuration. Collez votre code Mermaid, voyez le diagramme rendu et copiez le résultat.

C'est utile pour vérifier la syntaxe du diagramme avant de le commiter, pour partager une version rendue dans un message Slack ou pour prototyper un diagramme que vous allez ensuite coller dans un README.

Commencez par un diagramme de flux

Si vous n'avez jamais écrit un diagramme Mermaid, commencez par un diagramme de flux. Choisissez un processus dans votre codebase que vous avez voulu documenter — le cycle de requête, un travail en arrière-plan, un pipeline de déploiement — et écrivez-le en syntaxe Mermaid en moins de 10 minutes. Collez-le dans votre README dans un ```mermaid bloc et pousser-le. GitHub le rendra automatiquement.

Ce seul diagramme, contrôlé par version et vivant à côté du code qu'il décrit, vaut plus qu'une présentation partagée que personne ne croit.

Vous aimerez peut-être aussi