Mermaid Diagrams

Create diagrams and visualizations using Mermaid's text-based syntax.

Quick Reference

Diagram Types

Type	Syntax	Use Case
Flowchart	`flowchart`	Process flows, decisions
Sequence	`sequenceDiagram`	API calls, interactions
Class	`classDiagram`	OOP relationships
ERD	`erDiagram`	Database schemas
State	`stateDiagram-v2`	State machines
Gantt	`gantt`	Project timelines
Pie	`pie`	Proportions
Journey	`journey`	User experience

Flowcharts

Basic Flowchart

mermaid

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Node Shapes

mermaid

flowchart LR
    A[Rectangle] --> B(Rounded)
    B --> C([Stadium])
    C --> D[[Subroutine]]
    D --> E[(Database)]
    E --> F((Circle))
    F --> G>Asymmetric]
    G --> H{Diamond}
    H --> I{{Hexagon}}
    I --> J[/Parallelogram/]

Direction Options

code

TD - Top to Down
TB - Top to Bottom
BT - Bottom to Top
LR - Left to Right
RL - Right to Left

Arrow Types

mermaid

flowchart LR
    A --> B
    A --- C
    A -.-> D
    A ==> E
    A --text--> F
    A ---|text| G

Subgraphs

mermaid

flowchart TB
    subgraph Frontend
        A[React App]
        B[Vue App]
    end
    subgraph Backend
        C[API Server]
        D[Worker]
    end
    subgraph Database
        E[(PostgreSQL)]
        F[(Redis)]
    end
    A --> C
    B --> C
    C --> E
    D --> F

Sequence Diagrams

Basic Sequence

mermaid

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

code

->>   Solid line with arrowhead
-->>  Dotted line with arrowhead
-)    Solid line with open arrow
--)   Dotted line with open arrow
-x    Solid line with cross
--x   Dotted line with cross

Activations and Notes

mermaid

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>+S: Request
    Note right of S: Processing...
    S-->>-C: Response

    Note over C,S: Communication complete

Loops and Conditionals

mermaid

sequenceDiagram
    participant C as Client
    participant S as Server

    loop Every 5 seconds
        C->>S: Ping
        S-->>C: Pong
    end

    alt Success
        S-->>C: Data
    else Failure
        S-->>C: Error
    end

    opt Optional
        C->>S: Additional request
    end

Class Diagrams

Basic Class

mermaid

classDiagram
    class User {
        +String id
        +String name
        +String email
        +login()
        +logout()
    }

    class Order {
        +String id
        +Date date
        +Float total
        +process()
        +cancel()
    }

    User "1" --> "*" Order : places

Relationships

mermaid

classDiagram
    classA <|-- classB : Inheritance
    classC *-- classD : Composition
    classE o-- classF : Aggregation
    classG <-- classH : Association
    classI -- classJ : Link
    classK <.. classL : Dependency
    classM <|.. classN : Realization

Visibility

code

+ Public
- Private
# Protected
~ Package/Internal

Entity Relationship Diagrams

Basic ERD

mermaid

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "appears in"

    USER {
        int id PK
        string name
        string email UK
        date created_at
    }

    ORDER {
        int id PK
        int user_id FK
        date order_date
        float total
    }

    PRODUCT {
        int id PK
        string name
        float price
        int stock
    }

Relationship Types

code

||--|| : One to One
||--o{ : One to Zero or More
||--|{ : One to One or More
}o--o{ : Zero or More to Zero or More

State Diagrams

Basic State Machine

mermaid

stateDiagram-v2
    [*] --> Draft
    Draft --> Pending : Submit
    Pending --> Approved : Approve
    Pending --> Rejected : Reject
    Approved --> [*]
    Rejected --> Draft : Revise

Composite States

mermaid

stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Idle
        Idle --> Processing : Start
        Processing --> Idle : Complete
    }

    Active --> Suspended : Pause
    Suspended --> Active : Resume
    Active --> [*] : Terminate

Gantt Charts

Project Timeline

mermaid

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD

    section Planning
    Requirements    :a1, 2024-01-01, 7d
    Design          :a2, after a1, 10d

    section Development
    Backend         :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 Deployment
    Release         :milestone, after c2, 0d

Pie Charts

mermaid

pie title Technology Stack
    "JavaScript" : 40
    "Python" : 30
    "Go" : 15
    "Rust" : 10
    "Other" : 5

User Journey

mermaid

journey
    title User Checkout Journey
    section Browse
      Visit site: 5: User
      Search product: 4: User
      View product: 5: User
    section Purchase
      Add to cart: 4: User
      Checkout: 3: User
      Payment: 2: User
    section Delivery
      Confirmation: 5: User, System
      Shipping: 4: System
      Delivery: 5: System

Git Graphs

mermaid

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

Mindmaps

mermaid

mindmap
    root((Project))
        Frontend
            React
            TypeScript
            Tailwind
        Backend
            Node.js
            PostgreSQL
            Redis
        DevOps
            Docker
            Kubernetes
            GitHub Actions

Styling

Custom Styles

mermaid

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

Theme Configuration

mermaid

%%{init: {'theme': 'dark'}}%%
flowchart LR
    A --> B --> C

Markdown Integration

In Markdown Files

markdown

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

GitHub Support

GitHub natively renders Mermaid in markdown files, issues, and pull requests.

VS Code Extensions

•Markdown Preview Mermaid Support
•Mermaid Editor

Best Practices

•Use subgraphs - Group related elements
•Direction matters - Choose LR for processes, TD for hierarchies
•Label edges - Add text to clarify relationships
•Keep it simple - Avoid too many nodes in one diagram
•Use consistent styling - Apply class definitions
•Add titles - Include descriptive titles
•Break up complexity - Multiple diagrams over one complex one
•Use proper diagram type - Match diagram type to data
•Test rendering - Verify in target platform
•Document with diagrams - Embed in README and docs

When to Use This Skill

•Creating flowcharts for documentation
•Designing sequence diagrams for APIs
•Modeling database schemas with ERDs
•Visualizing class relationships
•Planning project timelines
•Documenting state machines
•Creating architecture diagrams