Mermaid Diagram Syntax: A Complete Guide

Mermaid is a text-based diagramming language that lets you create diagrams and visualizations using simple syntax inside Markdown files. Instead of using graphic design tools, you write a few lines of text and Mermaid converts them into professional SVG diagrams.

This guide covers the syntax for every major Mermaid diagram type with copy-paste examples you can use immediately. All examples can be rendered directly on your Android phone using MerMD.

1. Flowcharts

Flowcharts are the most common Mermaid diagram type. They’re used to visualize processes, decision trees, algorithms, and system architecture.

Basic Syntax

A flowchart starts with the graph keyword followed by a direction:

• graph TD — top to bottom (default)
• graph LR — left to right
• graph BT — bottom to top
• graph RL — right to left

Example: Basic Flowchart

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Fix it]
    D --> B

Renders as:

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Fix it]
    D --> B

Node Shapes

Mermaid supports different shapes to convey meaning:

graph LR
    A[Rectangle] --> B(Rounded)
    B --> C{Diamond}
    C --> D([Stadium])
    D --> E[[Subroutine]]
    E --> F[(Database)]
    F --> G((Circle))

Renders as:

graph LR
    A[Rectangle] --> B(Rounded)
    B --> C{Diamond}
    C --> D([Stadium])
    D --> E[[Subroutine]]
    E --> F[(Database)]
    F --> G((Circle))

• [text] — rectangle (default)
• (text) — rounded rectangle
• {text} — diamond (decision)
• ([text]) — stadium shape
• [[text]] — subroutine
• [(text)] — cylindrical (database)
• ((text)) — circle

Arrow Types

graph LR
    A --> B
    C --- D
    E -.-> F
    G ==> H
    I --text--> J

Renders as:

graph LR
    A --> B
    C --- D
    E -.-> F
    G ==> H
    I --text--> J

• --> — arrow
• --- — line (no arrow)
• -.-> — dotted arrow
• ==> — thick arrow
• --text--> — arrow with label

2. Sequence Diagrams

Sequence diagrams model interactions between components over time. They’re essential for documenting API calls, microservice communication, and authentication flows.

Basic Syntax

sequenceDiagram
    participant A as Client
    participant B as API Server
    participant C as Database

    A->>+B: POST /login
    B->>+C: SELECT user
    C-->>-B: User data
    B-->>-A: JWT Token

    A->>+B: GET /profile
    B->>B: Validate JWT
    B-->>-A: Profile data

Renders as:

sequenceDiagram
    participant A as Client
    participant B as API Server
    participant C as Database

    A->>+B: POST /login
    B->>+C: SELECT user
    C-->>-B: User data
    B-->>-A: JWT Token

    A->>+B: GET /profile
    B->>B: Validate JWT
    B-->>-A: Profile data

Arrow Types

• ->> — solid arrow (synchronous)
• -->> — dotted arrow (response)
• ->>+ — solid arrow with activation
• -->>- — dotted arrow with deactivation

Notes and Loops

sequenceDiagram
    Alice->>Bob: Hello Bob!
    Note right of Bob: Bob thinks
    Bob-->>Alice: Hi Alice!

    loop Every minute
        Alice->>Bob: Ping
        Bob-->>Alice: Pong
    end

    alt Success
        Alice->>Bob: Great
    else Failure
        Alice->>Bob: Retry
    end

Renders as:

sequenceDiagram
    Alice->>Bob: Hello Bob!
    Note right of Bob: Bob thinks
    Bob-->>Alice: Hi Alice!

    loop Every minute
        Alice->>Bob: Ping
        Bob-->>Alice: Pong
    end

    alt Success
        Alice->>Bob: Great
    else Failure
        Alice->>Bob: Retry
    end

3. Class Diagrams

Class diagrams visualize object-oriented structures — classes, interfaces, inheritance, and relationships. Perfect for UML documentation in your codebase.

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }

    class Dog {
        +String breed
        +fetch() void
    }

    class Cat {
        +bool isIndoor
        +purr() void
    }

    Animal <|-- Dog
    Animal <|-- Cat

Renders as:

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }

    class Dog {
        +String breed
        +fetch() void
    }

    class Cat {
        +bool isIndoor
        +purr() void
    }

    Animal <|-- Dog
    Animal <|-- Cat

Relationship Types

• <|-- — inheritance
• *-- — composition
• o-- — aggregation
• --> — association
• .. — dependency (dotted)
• ..|> — realization/interface

4. Gantt Charts

Gantt charts display project timelines, task dependencies, and milestones. They’re invaluable for sprint planning and project documentation.

gantt
    title Project Launch Timeline
    dateFormat  YYYY-MM-DD

    section Design
    Wireframes          :done, des1, 2026-01-01, 14d
    UI Mockups          :done, des2, after des1, 10d
    Design Review       :milestone, m1, after des2, 0d

    section Development
    Backend API         :active, dev1, 2026-01-20, 30d
    Frontend UI         :dev2, after des2, 25d
    Integration         :dev3, after dev1, 10d

    section Testing
    QA Testing          :test1, after dev3, 14d
    Launch              :milestone, m2, after test1, 0d

Renders as:

gantt
    title Project Launch Timeline
    dateFormat  YYYY-MM-DD

    section Design
    Wireframes          :done, des1, 2026-01-01, 14d
    UI Mockups          :done, des2, after des1, 10d
    Design Review       :milestone, m1, after des2, 0d

    section Development
    Backend API         :active, dev1, 2026-01-20, 30d
    Frontend UI         :dev2, after des2, 25d
    Integration         :dev3, after dev1, 10d

    section Testing
    QA Testing          :test1, after dev3, 14d
    Launch              :milestone, m2, after test1, 0d

Task Status Keywords

• done — completed task
• active — in-progress task
• crit — critical task (highlighted in red)
• milestone — milestone marker

5. Entity-Relationship (ER) Diagrams

ER diagrams model database schemas, showing entities, attributes, and relationships between tables.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"
    CUSTOMER {
        int id PK
        string name
        string email
    }
    ORDER {
        int id PK
        date created_at
        string status
    }
    PRODUCT {
        int id PK
        string name
        float price
    }

Renders as:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"
    CUSTOMER {
        int id PK
        string name
        string email
    }
    ORDER {
        int id PK
        date created_at
        string status
    }
    PRODUCT {
        int id PK
        string name
        float price
    }

Relationship Cardinality

• ||--|| — one-to-one
• ||--o{ — one-to-many
• }o--o{ — many-to-many
• ||--|{ — one-to-many (mandatory)

6. Pie Charts

Pie charts visualize proportional data distributions. Simple and effective for reports.

pie title Language Usage
    "JavaScript" : 35
    "Python" : 25
    "Kotlin" : 20
    "Rust" : 12
    "Other" : 8

Renders as:

pie title Language Usage
    "JavaScript" : 35
    "Python" : 25
    "Kotlin" : 20
    "Rust" : 12
    "Other" : 8

7. State Diagrams

State diagrams model the states and transitions of a system or object — ideal for documenting state machines, UI flows, and workflow engines.

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : Submit
    Review --> Approved : Approve
    Review --> Draft : Request Changes
    Approved --> Published : Publish
    Published --> [*]

Renders as:

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : Submit
    Review --> Approved : Approve
    Review --> Draft : Request Changes
    Approved --> Published : Publish
    Published --> [*]

8. User Journey Maps

Journey maps visualize user experiences across different tasks and stages, rating satisfaction at each step.

journey
    title User Onboarding Journey
    section Download
        Find on Play Store: 5: User
        Install app: 5: User
    section First Use
        Open app: 4: User
        Browse files: 4: User
        View Markdown: 5: User
    section Advanced
        Connect GitHub: 3: User
        Export to PDF: 4: User

Renders as:

journey
    title User Onboarding Journey
    section Download
        Find on Play Store: 5: User
        Install app: 5: User
    section First Use
        Open app: 4: User
        Browse files: 4: User
        View Markdown: 5: User
    section Advanced
        Connect GitHub: 3: User
        Export to PDF: 4: User

Viewing Mermaid Diagrams on Mobile

All the examples in this guide can be viewed on your Android phone using MerMD. Simply paste the code into a .md file and open it in MerMD — the diagrams will render natively, completely offline.

MerMD supports every Mermaid diagram type covered in this guide: flowcharts, sequence diagrams, class diagrams, Gantt charts, ER diagrams, pie charts, state diagrams, and journey maps.