Mermaid syntax cheat sheet: all diagram types at a glance

Mermaid syntax is simple once you know the patterns, but there are eight major diagram types and each has its own keywords and arrows. This cheat sheet covers every one—copy, paste, and adapt.

Flowchart (decision trees and processes)

flowchart TD
    A([Start]) --> B[Step]
    B --> C{Decision?}
    C -->|Yes| D["Action A"]
    C -->|No| E["Action B"]
    D --> F([End])
    E --> F
    style F fill:#e1f5e1

Key syntax:

• flowchart TD (top-down) or LR (left-right)
• [text] = rectangle
• ([text]) = rounded (start/end)
• {text} = diamond (decision)
• [(text)] = cylinder (data store)
• --> or ---> = arrow
• -->|Label| = labeled arrow
• style ID fill:#color = color a node

Sequence diagram (interactions over time)

sequenceDiagram
    participant C as Client
    participant A as API
    participant DB as Database

    C->>A: Request
    A->>+DB: Query
    DB-->>-A: Result
    A-->>C: Response
    Note over C,A: Request done

Key syntax:

• sequenceDiagram opens the diagram
• participant X as Full Name (optional alias)
• ->> = sync call (solid arrow)
• -->> = response (dashed arrow)
• -x = fire-and-forget (arrow with X)
• + after participant = open activation box; - = close
• alt/else/end = branching
• loop condition / end = repeat
• Note over X or Note left of X = annotation
• opt condition / end = optional flow

Class diagram (OOP structure)

classDiagram
    class User {
        +id: int
        +name: string
        +email: string
        +login()
        +logout()
    }

    class Post {
        +id: int
        +title: string
        +author_id: int
        +publish()
    }

    User "1" --> "*" Post : creates

Key syntax:

• class ClassName { } = class definition
• +name: type = public property
• #name: type = protected
• -name: type = private
• method() = method (no return type shown)
• "cardinality" --> "cardinality" = relationship
• <|-- = inheritance
• *-- = composition
• o-- = aggregation

State diagram (state machines)

stateDiagram-v2
    [*] --> Idle
    Idle --> Running: start()
    Running --> Paused: pause()
    Paused --> Running: resume()
    Running --> Idle: stop()
    Idle --> [*]

Key syntax:

• stateDiagram-v2 opens the diagram
• [*] = start or end state
• State1 --> State2 = transition (no label, implicit)
• State1 --> State2: event = transition with trigger
• state ID { nested diagram } = composite state
• -- = internal transition

Entity-Relationship (ER) diagram (database schema)

erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        int customer_id PK
        string name
        string email UK
    }
    ORDER {
        int order_id PK
        int customer_id FK
        date order_date
        decimal total
    }
    ORDER ||--|{ LINE_ITEM : contains
    LINE_ITEM {
        int item_id PK
        int order_id FK
        int product_id FK
        int quantity
    }

Key syntax:

• ENTITY { } = table/entity
• int column_name = column with type
• PK = primary key
• FK = foreign key
• UK = unique
• || = one
• o{ or }o = zero or more
• |{ or }| = one or more
• ||--o{ = one-to-many

Gantt chart (timelines and schedules)

gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    
    section Phase 1
    Design :design, 2026-06-13, 10d
    Review :review, after design, 5d
    
    section Phase 2
    Dev :active, dev, 2026-06-13, 20d
    Testing :test, after dev, 10d
    
    section Phase 3
    Deployment :deploy, after test, 3d

Key syntax:

• gantt opens the chart
• dateFormat YYYY-MM-DD = date parsing
• section Name = swimlane
• Task :status, id, start, duration = task
• status can be done, active, crit, milestone
• after id = start after another task
• dateFormat, axisFormat, tickInterval = formatting

Git graph (branching and merges)

gitGraph
    commit id: "Initial commit"
    commit id: "Add auth"
    
    branch feature/user-profile
    checkout feature/user-profile
    commit id: "Profile page"
    commit id: "Edit form"
    
    checkout main
    branch bugfix/login
    checkout bugfix/login
    commit id: "Fix token"
    
    checkout main
    merge bugfix/login
    checkout feature/user-profile
    commit id: "Validation"
    checkout main
    merge feature/user-profile

Key syntax:

• gitGraph opens the diagram
• commit id: "msg" = commit
• branch name = create branch
• checkout name = switch to branch
• merge name = merge branch into current
• tag name = add tag

Pie chart (distribution and percentages)

pie title Frontend resource usage
    "JavaScript" : 45
    "CSS" : 25
    "HTML" : 20
    "Assets" : 10

Key syntax:

• pie title Text = pie with title
• "Label" : value = slice (value is relative, not percent)
• Values are proportional, not literal percentages

Mindmap (hierarchical brainstorming)

mindmap
  root((Mermaid))
    Diagram Types
      Flowchart
      Sequence
      State
    Use Cases
      Documentation
      Design
      Planning
    Benefits
      Portable
      Version-controlled
      Easy to read

Key syntax:

• mindmap opens the diagram
• root((Topic)) = center node
• Indentation = hierarchy (each level deeper is a child)
• (text) = circle; [text] = square; text = no shape

C4 model (system architecture)

C4Context
    title System Context Diagram
    Person(user, "User", "A human using the system")
    System(web, "Web App", "The application")
    System_Ext(email, "Email System", "External service")
    
    Rel(user, web, "Uses")
    Rel(web, email, "Sends via")

Key syntax:

• C4Context, C4Container, C4Component, C4Deployment = diagram type
• Person(id, "Name", "Description")
• System(id, "Name", "Description")
• System_Ext(id, "Name", "Description") = external system
• Rel(source, target, "Label") = relationship

Sankey diagram (flow magnitude)

sankey-beta

Energy,Coal,300
Energy,Natural Gas,200
Energy,Solar,100

Coal,Electricity,280
Natural Gas,Electricity,200
Solar,Electricity,100

Electricity,Industrial,280
Electricity,Residential,220

Key syntax:

• sankey-beta opens the diagram
• Source,Target,Value = flow line
• Values determine the width of each path

Quick syntax reference

Concept	Syntax
Comment	%% Comment
Subgraph (flowchart)	subgraph ID [Label] ... end
Arrow directions	--> (right), <-- (left), <--> (both)
Thick arrow	---> (three dashes)
Dotted arrow	-.-
Link text	--> |text|
Node ID	ID[Label] or refer by ID alone

Tips for clean syntax

1. Use descriptive IDs — UserAuth instead of A makes diagrams readable
2. Comment complex sections — %% Authentication flow helps future readers
3. Break long labels — use <br/> for multi-line text in nodes
4. Consistency — pick either camelCase or snake_case for IDs and stick with it
5. Test small — build incrementally and render often to catch typos early

Rendering your diagrams

Paste any of these blocks into MermaidCreator's playground to edit, refine, and export as PNG or SVG. Or paste them directly into GitHub, Notion, GitLab, or any tool that supports Mermaid.

FAQ

Which diagram should I use for X? Use our diagram comparison guide to choose between flowchart, sequence, and state. For others, the Mermaid docs have a type guide.

Can I combine diagram types? No — each type stands alone. For complex systems, create multiple diagrams (context → containers → components).

Where do I find more syntax details? The Mermaid documentation has deep syntax reference for every type.

Keep this cheat sheet handy and you'll never be stuck on Mermaid syntax again.