Mermaid Diagrams

Overview

Mermaid is a markdown-based diagramming tool that renders in GitHub, GitLab, Notion, and documentation sites. Use this skill to create visual diagrams in markdown files.

When to Use

• Documenting system architecture
• Visualizing API flows and sequences
• Creating database ER diagrams
• Illustrating state machines
• Project timelines and Gantt charts
• Git branch strategies

Basic Syntax

```mermaid
flowchart LR
    A --> B --> C
```

Flowcharts

Direction

flowchart TB    %% Top to Bottom
flowchart BT    %% Bottom to Top
flowchart LR    %% Left to Right
flowchart RL    %% Right to Left

Node Shapes

flowchart LR
    A[Rectangle]
    B(Rounded)
    C([Stadium])
    D[[Subroutine]]
    E[(Database)]
    F((Circle))
    G>Flag]
    H{Diamond}
    I{{Hexagon}}
    J[/Parallelogram/]
    K[\Parallelogram Alt\]
    L[/Trapezoid\]

Connections

flowchart LR
    A --> B                 %% Arrow
    A --- B                 %% Line
    A -.-> B                %% Dotted arrow
    A ==> B                 %% Thick arrow
    A --text--> B           %% Arrow with text
    A -->|text| B           %% Alt text syntax
    A <--> B                %% Bidirectional

Subgraphs

flowchart TB
    subgraph Frontend
        A[React App]
        B[Next.js]
    end
    subgraph Backend
        C[API Server]
        D[(Database)]
    end
    A --> C
    B --> C
    C --> D

Styling

flowchart LR
    A[Start]:::green --> B[Process]:::blue --> C[End]:::red
    
    classDef green fill:#9f6,stroke:#333
    classDef blue fill:#69f,stroke:#333
    classDef red fill:#f66,stroke:#333

Sequence Diagrams

Basic Sequence

sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database
    
    U->>A: POST /login
    A->>D: Query user
    D-->>A: User data
    A-->>U: JWT token

Arrow Types

->>     Solid arrow
-->>    Dotted arrow
-x      Solid cross (async)
--x     Dotted cross
-)      Open arrow
--)     Dotted open arrow

Activations & Notes

sequenceDiagram
    participant C as Client
    participant S as Server
    
    C->>+S: Request
    Note right of S: Processing...
    S-->>-C: Response
    
    Note over C,S: Connection established

Loops & Conditionals

sequenceDiagram
    participant C as Client
    participant S as Server
    
    loop Every 30s
        C->>S: Heartbeat
    end
    
    alt Success
        S-->>C: 200 OK
    else Error
        S-->>C: 500 Error
    end
    
    opt Optional Step
        C->>S: Analytics
    end

Entity Relationship Diagrams

erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }
    ORDER ||--|{ ORDER_ITEM : contains
    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
    }
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
    PRODUCT {
        int id PK
        string name
        decimal price
    }

Relationship Types

||--||    One to one
||--o{    One to many
}o--o{    Many to many
||--|{    One to one or many

State Diagrams

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: Submit
    Review --> Draft: Request Changes
    Review --> Approved: Approve
    Approved --> Published: Publish
    Published --> [*]
    
    state Review {
        [*] --> Pending
        Pending --> InProgress: Assign
        InProgress --> Complete: Finish
        Complete --> [*]
    }

Transitions & Notes

stateDiagram-v2
    [*] --> Active
    Active --> Inactive: timeout
    Inactive --> Active: wake
    Active --> [*]: terminate
    
    note right of Active: Processing requests
    note left of Inactive: Sleeping

Class Diagrams

classDiagram
    class User {
        +int id
        +string email
        +string name
        +login()
        +logout()
    }
    class Order {
        +int id
        +decimal total
        +string status
        +calculate()
        +submit()
    }
    class Product {
        +int id
        +string name
        +decimal price
    }
    
    User "1" --> "*" Order: places
    Order "*" --> "*" Product: contains

Visibility & Relationships

+   Public
-   Private
#   Protected
~   Package

<|--    Inheritance
*--     Composition
o--     Aggregation
-->     Association
..>     Dependency
..|>    Realization

Gantt Charts

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    
    section Planning
    Requirements    :a1, 2024-01-01, 7d
    Design          :a2, after a1, 5d
    
    section Development
    Backend API     :b1, after a2, 14d
    Frontend        :b2, after a2, 14d
    Integration     :b3, after b1, 7d
    
    section Testing
    QA Testing      :c1, after b3, 7d
    UAT             :c2, after c1, 5d
    
    section Launch
    Deployment      :milestone, after c2, 0d

Git Graphs

gitGraph
    commit id: "Initial"
    branch develop
    checkout develop
    commit id: "Feature A"
    commit id: "Feature B"
    checkout main
    merge develop id: "Release 1.0"
    branch hotfix
    commit id: "Fix bug"
    checkout main
    merge hotfix id: "Patch 1.0.1"

Pie Charts

pie showData
    title Browser Market Share
    "Chrome" : 65
    "Safari" : 19
    "Firefox" : 10
    "Edge" : 4
    "Other" : 2

Mindmaps

mindmap
    root((Project))
        Frontend
            React
            TypeScript
            Tailwind
        Backend
            Node.js
            PostgreSQL
            Redis
        DevOps
            Docker
            Kubernetes
            CI/CD

Timeline

timeline
    title Product Roadmap
    section Q1
        January : Feature A : Feature B
        February : Feature C
        March : Release 1.0
    section Q2
        April : Feature D
        May : Feature E : Feature F
        June : Release 2.0

Common Patterns

API Flow

sequenceDiagram
    participant C as Client
    participant G as API Gateway
    participant A as Auth Service
    participant S as Service
    participant D as Database
    
    C->>G: Request + Token
    G->>A: Validate Token
    A-->>G: Valid
    G->>S: Forward Request
    S->>D: Query
    D-->>S: Data
    S-->>G: Response
    G-->>C: Response

Microservices Architecture

flowchart TB
    subgraph Client
        Web[Web App]
        Mobile[Mobile App]
    end
    
    subgraph Gateway
        AG[API Gateway]
        LB[Load Balancer]
    end
    
    subgraph Services
        US[User Service]
        OS[Order Service]
        PS[Product Service]
        NS[Notification Service]
    end
    
    subgraph Data
        UD[(User DB)]
        OD[(Order DB)]
        PD[(Product DB)]
        MQ[Message Queue]
    end
    
    Web --> LB
    Mobile --> LB
    LB --> AG
    AG --> US & OS & PS
    US --> UD
    OS --> OD
    PS --> PD
    OS --> MQ
    MQ --> NS

CI/CD Pipeline

flowchart LR
    subgraph Source
        GH[GitHub]
    end
    
    subgraph CI
        Build[Build]
        Test[Test]
        Lint[Lint]
    end
    
    subgraph CD
        Stage[Staging]
        Prod[Production]
    end
    
    GH -->|push| Build
    Build --> Test & Lint
    Test & Lint -->|pass| Stage
    Stage -->|approve| Prod

Tips

• Use %% for comments
• Keep diagrams focused (split large ones)
• Test rendering in GitHub/target platform
• Use meaningful IDs for nodes
• Leverage subgraphs for organization

Rendering

Platform	Support
GitHub	✅ Native in .md files
GitLab	✅ Native in .md files
Notion	✅ Code block type "mermaid"
VS Code	✅ With extension
Docusaurus	✅ Plugin available
Obsidian	✅ Native support