Mermaid Diagram Syntax Guide

Dense reference for creating diagrams. Each section shows the declaration keyword, essential syntax, and a working example.

Flowchart

Most common diagram type. Shows processes, decisions, and flows.

Declaration: flowchart TD (top-down) or flowchart LR (left-right)

Nodes: A[Rectangle], B(Rounded), C{Diamond}, D([Stadium]), E[[Subroutine]], F[(Database)], G((Circle))

Arrows: --> solid, -.-> dotted, ==> thick, --text--> labeled

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

Sequence Diagram

Interactions between actors over time. Great for API flows, protocols, conversations.

Declaration: sequenceDiagram

Messages: -> solid, --> dotted, ->> solid arrow, -->> dotted arrow

Activation: activate Actor / deactivate Actor or use +/- suffix

Notes: Note right of A: text, Note over A,B: text

sequenceDiagram
    participant User
    participant API
    participant DB
    User->>+API: POST /login
    API->>+DB: Query user
    DB-->>-API: User data
    API-->>-User: JWT token
    Note over User,API: Auth complete

Class Diagram

UML class diagrams for object-oriented design.

Declaration: classDiagram

Class: class ClassName or inline with members

Relationships: <|-- inheritance, *-- composition, o-- aggregation, --> association, ..> dependency

Visibility: + public, - private, # protected

classDiagram
    Animal <|-- Dog
    Animal <|-- Cat
    Animal : +String name
    Animal : +makeSound()
    Dog : +fetch()
    Cat : +scratch()

State Diagram

State machines and transitions. Good for lifecycle flows.

Declaration: stateDiagram-v2

States: state "Description" as alias, [*] for start/end

Transitions: --> with optional labels

Composite: state StateName { } for nested states

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: Submit
    Review --> Approved: Accept
    Review --> Draft: Reject
    Approved --> Published: Publish
    Published --> [*]

Entity Relationship Diagram

Database schemas and relationships.

Declaration: erDiagram

Cardinality: || one, o| zero or one, }| many, }o zero or many

Attributes: Listed inside entity block

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"
    USER {
        int id PK
        string email UK
        string name
    }
    ORDER {
        int id PK
        date created_at
    }

Gantt Chart

Project timelines, schedules, dependencies.

Declaration: gantt

Sections: section Name groups tasks

Tasks: TaskName :status, id, start, duration or after id

Status: done, active, crit (critical)

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Planning
        Research      :done, p1, 2024-01-01, 7d
        Design        :active, p2, after p1, 5d
    section Development
        Backend       :crit, d1, after p2, 14d
        Frontend      :d2, after p2, 14d
    section Launch
        Testing       :after d1 d2, 7d
        Deploy        :2d

Pie Chart

Simple proportional data visualization.

Declaration: pie

Entries: "Label" : value

pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 19
    "Firefox" : 8
    "Edge" : 5
    "Other" : 3

Mindmap

Hierarchical brainstorming and idea organization.

Declaration: mindmap

Hierarchy: Indentation defines levels. Root has no indent.

Shapes: [Square], (Rounded), ))Cloud((, {{Hexagon}}

mindmap
    root((Project))
        Planning
            Requirements
            Timeline
        Development
            Frontend
                React
                CSS
            Backend
                API
                Database
        Launch
            Testing
            Deploy

Timeline

Chronological events with periods.

Declaration: timeline

Periods: section Period Name or just list events

timeline
    title Company History
    section Founding
        2010 : Company founded
        2011 : First product launch
    section Growth
        2015 : Series A funding
        2018 : IPO
    section Present
        2024 : Global expansion

Git Graph

Branch and commit visualization.

Declaration: gitGraph

Commands: commit, branch name, checkout name, merge name

gitGraph
    commit id: "Initial"
    branch feature
    checkout feature
    commit id: "Add feature"
    commit id: "Fix bug"
    checkout main
    merge feature
    commit id: "Release"

Quadrant Chart

2x2 matrices for categorization (priority, impact/effort, etc.).

Declaration: quadrantChart

Axes: x-axis, y-axis with labels

Quadrants: quadrant-1 through quadrant-4 for labels

Points: PointName: [x, y] where x,y are 0-1

quadrantChart
    title Priority Matrix
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Do First
    quadrant-2 Schedule
    quadrant-3 Delegate
    quadrant-4 Eliminate
    Feature A: [0.2, 0.9]
    Feature B: [0.8, 0.8]
    Feature C: [0.3, 0.2]

User Journey

Experience mapping across touchpoints.

Declaration: journey

Sections: section Name groups steps

Steps: Step description: score: Actor1, Actor2

journey
    title Checkout Experience
    section Discovery
        Browse products: 5: Customer
        Add to cart: 4: Customer
    section Checkout
        Enter details: 3: Customer
        Payment: 2: Customer, System
    section Delivery
        Confirmation: 5: System
        Receive order: 5: Customer

Styling Tips

Themes: Add %%{init: {'theme': 'forest'}}%% at the start. Options: default, forest, dark, neutral, base.

Node styling: style NodeId fill:#f9f,stroke:#333,stroke-width:2px

Link styling: linkStyle 0 stroke:#ff0000 (0-indexed links)

Class definitions: classDef className fill:#fff then A:::className

Common Gotchas

• No spaces in node IDs. Use UserService not User Service. Labels can have spaces: A[User Service].
• Quote labels with special characters. A["Process (main)"] not A[Process (main)].
• Escape pipes in labels. Use #124; for | inside labels.
• Avoid reserved words as IDs: end, subgraph, graph — use endNode, subGraph1.
• Semicolons optional but help readability in complex diagrams.
• Direction matters: TB/TD (top-bottom), BT (bottom-top), LR (left-right), RL (right-left).