Mermaid Syntax Cheatsheet

To write a flowchart in Mermaid, start the block with flowchart TD for a top-down layout (or LR for left-to-right), then declare each node with an id and a bracketed label — square brackets for a rectangle, curly braces for a decision diamond — and connect nodes with --> arrows. Add a label to any arrow by writing it between pipes, as in B -->|Yes| C.

flowchart TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Ship it]
    B -->|No| D[Debug]
    D --> B
    C --> E(Done)

To write a sequence diagram in Mermaid, open with sequenceDiagram, declare each participant on its own line (participant S as Server gives it a display alias), then write one message per line: a solid arrow ->> for a request and a dashed -->> for the reply. Participants render left to right in declaration order, and messages stack top to bottom in the order written.

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database
    C->>S: POST /login
    S->>DB: SELECT user WHERE email=?
    DB-->>S: User record
    S-->>C: 200 OK + JWT token

To make a Gantt chart in Mermaid, start with gantt, set dateFormat YYYY-MM-DD, and group tasks under section headings. Each task is one line: a name, an optional status tag such as done, active, or crit, an id, then either explicit dates or a duration like 5d. Chain dependent work by writing after taskId in place of a start date.

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Design
        Wireframes     :done, des1, 2024-01-01, 2024-01-07
        Mockups        :active, des2, 2024-01-08, 5d
    section Development
        Frontend       :dev1, after des2, 10d
        Backend        :dev2, after des2, 14d
    section Launch
        Deploy         :milestone, 2024-02-15, 0d

To write an ER diagram in Mermaid, start with erDiagram, define each entity as a block listing its attributes with a type and a name (marking keys PK or FK), then declare relationships between entities with cardinality symbols — ||--o{ reads as one-to-many. The quoted label after the colon describes how the two entities relate.

erDiagram
    USER {
        int id PK
        string email
        string name
        date created_at
    }
    POST {
        int id PK
        string title
        text body
        int user_id FK
    }
    USER ||--o{ POST : "writes"

To write a class diagram in Mermaid, start with classDiagram and define each class as a block containing its attributes and methods, prefixed + for public or - for private. Then draw relationships between class names: <|-- for inheritance, *-- for composition, and o-- for aggregation.

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +bool indoor
        +purr() void
    }
    Animal <|-- Dog
    Animal <|-- Cat

To write a state diagram in Mermaid, start with stateDiagram-v2, use [*] for the start and end states, and describe each transition as CurrentState --> NextState : trigger. Attach context to any state with note right of, and nest sub-states inside state Name { } blocks when a state has internal structure.

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : submit
    Processing --> Success : valid
    Processing --> Error : invalid
    Error --> Idle : retry
    Success --> [*]
    note right of Processing
        Validating input
        and calling API
    end note

To make a pie chart in Mermaid, start with pie and an optional title on the same line, then list one slice per line as a quoted label, a colon, and its numeric value. Mermaid computes the percentages automatically, so values can be raw counts rather than percentages.

pie title Browser Market Share
    "Chrome" : 65.3
    "Safari" : 18.7
    "Firefox" : 4.1
    "Edge" : 4.2
    "Other" : 7.7

To draw a git graph in Mermaid, start with gitGraph and write git operations in order: commit adds a commit to the current branch, branch creates and switches to a new branch, checkout switches between existing branches, and merge brings another branch back in. Give commits readable labels with commit id: "message".

gitGraph
   commit id: "initial"
   branch feature/auth
   checkout feature/auth
   commit id: "add login"
   commit id: "add JWT"
   checkout main
   merge feature/auth
   commit id: "bump version"

To make a mindmap in Mermaid, start with mindmap and put the central idea on the next line — wrapping it in double parentheses draws it as a circle. Every following line becomes a node, and its depth of indentation decides which branch it hangs from, so the whole map is written as a plain indented outline.

mindmap
  root((FlowViz))
    Features
      Real-time preview
      SVG export
      Theme switching
    Diagram Types
      Flowchart
      Sequence
      Gantt
    Tech Stack
      Vue 3
      Mermaid v11
      Nuxt 3

To make a timeline in Mermaid, start with timeline, add a title, and group periods under section headings. Each entry is a period, a colon, and its event — add more colon-separated events on following lines to attach several events to the same period.

timeline
    title Product Roadmap
    section 2024 Q1
        Jan : Beta launch
        Feb : User feedback
        Mar : v1.0 release
    section 2024 Q2
        Apr : Mobile support
        Jun : API access

To make a quadrant chart in Mermaid, start with quadrantChart, label the x-axis and y-axis with Low --> High ranges, and name the four quadrants with quadrant-1 through quadrant-4. Then plot each item as Name: [x, y] using coordinates between 0 and 1, where [1, 1] is the top-right corner.

quadrantChart
    title Feature prioritization
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Strategic bets
    quadrant-2 Quick wins
    quadrant-3 Deprioritize
    quadrant-4 Money pits
    Dark mode: [0.25, 0.75]
    SSO login: [0.8, 0.85]
    New icons: [0.2, 0.3]
    Full rewrite: [0.9, 0.35]

To make a sankey diagram in Mermaid, start with sankey-beta and list one flow per line as unindented CSV: source, target, value. Reuse a node name as the source of later rows to chain flows through multiple stages — Mermaid sizes every ribbon in proportion to its value.

sankey-beta
Visitors,Signed up,300
Visitors,Bounced,700
Signed up,Activated,180
Signed up,Dropped off,120
Activated,Paying,60
Activated,Free tier,120

To make a bar or line chart in Mermaid, start with xychart-beta, define the x-axis with a bracketed list of categories and the y-axis with a label and range, then plot the series with bar [...] or line [...] — or both, to overlay a line on the bars. Values match categories by position.

xychart-beta
    title "Monthly revenue"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Revenue ($k)" 0 --> 120
    bar [42, 55, 61, 74, 88, 105]
    line [42, 55, 61, 74, 88, 105]

To make a block diagram in Mermaid, start with block-beta and set the grid with columns N. Each entry then fills the next cell — use space to leave a cell empty and shape brackets such as DB[("Postgres")] to style a block — and connections are drawn afterwards with --> arrows between block ids.

block-beta
columns 3
  Client space:1 API["API Gateway"]
  space:3
  Cache[("Redis")] space:1 DB[("Postgres")]
  Client --> API
  API --> DB
  API --> Cache

To draw an architecture diagram in Mermaid, start with architecture-beta, declare group blocks for boundaries such as clouds or VPCs, then add service entries with a built-in icon (database, server, disk) and place them inside a group with the in keyword. Connect services edge to edge with db:L -- R:server, where the letters pick which side each line attaches to.

architecture-beta
    group api(cloud)[API]

    service db(database)[Database] in api
    service disk1(disk)[Storage] in api
    service server(server)[Server] in api

    db:L -- R:server
    disk1:T -- B:db

To make a user journey diagram in Mermaid, start with journey, group steps under section headings, and write each step as Task name: score: Actor, scoring the experience from 1 (worst) to 5 (best). Mermaid colors every step by its score, which makes the painful parts of the journey stand out at a glance.

journey
    title Checkout experience
    section Browse
      Find product: 5: Shopper
      Compare prices: 3: Shopper
    section Purchase
      Add to cart: 4: Shopper
      Enter payment: 2: Shopper
      Confirm order: 5: Shopper, Support

To write a requirement diagram in Mermaid, start with requirementDiagram and declare each requirement as a block with an id, text, risk level, and verifymethod. Declare the system parts as element blocks, then connect them with typed relations such as auth_service - satisfies -> login_req to show which element covers which requirement.

requirementDiagram

    requirement login_req {
    id: 1
    text: Users must authenticate before accessing data.
    risk: high
    verifymethod: test
    }

    element auth_service {
    type: service
    }

    auth_service - satisfies -> login_req

To draw a C4 context diagram in Mermaid, start with C4Context (or C4Container and C4Component for deeper zoom levels), declare people and systems with Person(id, "Label", "Description") and System(...), using System_Ext for systems outside your boundary, then relate them with Rel(from, to, label, technology).

C4Context
    title Internet banking - system context
    Person(customer, "Customer", "A customer of the bank")
    System(banking, "Internet Banking", "Lets customers view accounts")
    System_Ext(mail, "E-mail System", "Sends notifications")
    Rel(customer, banking, "Uses")
    Rel(banking, mail, "Sends e-mails", "SMTP")

To make a kanban board in Mermaid, start with kanban, write each column as a top-level id[Title] entry, and indent card entries beneath the column they belong to. Columns render left to right in declaration order, so moving a card between columns is just cutting one line and pasting it under another heading.

kanban
  todo[Todo]
    t1[Write API spec]
    t2[Design schema]
  doing[In progress]
    t3[Build endpoints]
  done[Done]
    t4[Project setup]

To make a radar chart in Mermaid, start with radar-beta, define the spokes with axis entries, then plot each entity as a curve listing one value per axis in declaration order. Set min and max to fix the scale so curves from different entities are directly comparable.

radar-beta
  title Team skills
  axis c["Coding"], d["Design"], o["Ops"]
  axis p["Product"], m["Marketing"]
  curve alice["Alice"]{80, 60, 70, 55, 40}
  curve bob["Bob"]{55, 85, 45, 75, 70}
  max 100
  min 0

To draw a packet diagram in Mermaid, start with packet-beta and describe each field as a bit range with a quoted name, such as 0-15: "Source Port". Rows wrap automatically at 32 bits, producing the classic RFC-style layout for network headers and binary formats.

packet-beta
0-15: "Source Port"
16-31: "Destination Port"
32-63: "Sequence Number"
64-95: "Acknowledgment Number"