Mermaid cheatsheet

One page, every diagram type. Each block is a complete, working example — paste it straight into the editor. Print-friendly: use your browser's print dialog for a paper copy.

Flowchart

flowchart TD
  A[Start] --> B{Valid?}
  B -- Yes --> C[Process]
  B -- No --> D[Reject]
  C --> E[(Database)]
  D --> F([End])
  • Directions: TB (top-down), LR, RL, BT.
  • Shapes: [rect] (stadium) {diamond} [(database)] ((circle))
  • Edge labels: A -- text --> B or A -->|text| B
  • Dotted arrows: A -.-> B · thick: A ==> B

Sequence diagram

sequenceDiagram
  autonumber
  actor U as User
  participant S as Server
  U->>S: Request
  S-->>U: Response
  U->>+S: Activate
  S-->>-U: Done
  Note over U,S: Session ends
  • Solid arrow ->>, dashed return -->>.
  • Activate/deactivate: ->>+ and -->>- (must balance).
  • Blocks: alt/else/end, loop … end, opt … end.
  • Declare participants before first use.

Class diagram

classDiagram
  class Animal {
    +String name
    +makeSound()
  }
  class Dog {
    +fetch()
  }
  Animal <|-- Dog
  Animal : +int age
  • Visibility: + public, - private, # protected, ~ package.
  • Relations: <|-- inheritance, --> association, ..|> realization, o-- aggregation, *-- composition.
  • Cardinality: Dog "1" --> "*" Bone

State diagram

stateDiagram-v2
  [*] --> Idle
  Idle --> Running: start
  Running --> Paused: pause
  Paused --> Running: resume
  Running --> [*]: stop
  • Always use stateDiagram-v2 (v1 is legacy).
  • [*] marks start and end states.
  • Transition labels come after a colon.
  • Composite states: state Group { … }

ER diagram

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  CUSTOMER {
    string name
    string email
  }
  • Crow notation: || exactly one, o| zero or one, }o zero or more, }| one or more.
  • Pattern: LEFT <rel> RIGHT : label, e.g. A ||--o{ B : has
  • Attribute blocks list type then name.

Gantt chart

gantt
  title Launch plan
  dateFormat YYYY-MM-DD
  axisFormat %b %d
  section Build
    Design :a1, 2026-01-05, 7d
    Develop :a2, after a1, 14d
  section Ship
    Release :milestone, after a2, 0d
  • dateFormat must match task dates (default YYYY-MM-DD).
  • Durations: 7d, 2w · Dependencies: after a1.
  • Milestones use :milestone, …, 0d.

Pie chart

pie showData
  title Traffic
  "Organic" : 45
  "Direct" : 25
  "Social" : 30
  • showData displays the underlying value table.
  • Label : number — quote labels with spaces or special characters.

Mindmap

mindmap
  root((Product))
    Features
      Search
      Export
    Teams
      Design
  • Indentation defines hierarchy — spaces only, never tabs.
  • Root shapes: root((text)), root[text], root(text).
  • Icons via ::icon() are optional.

Timeline

timeline
  title Roadmap
  2026-09 : Beta
  2026-10 : Launch
  2026-11 : Mobile app
  • Period : Event — one event per line.
  • Multiple events: 2026 : A : B (colon-separated).
  • section blocks group periods.

User journey

journey
  title Onboarding
  section Discover
    Land on site: 5: User
    Read docs: 4: User
  section Try
    Paste code: 5: User
  • Task format: Name: score: Actor (score 1-5).
  • section groups tasks into phases.
  • Multiple actors: Task: 4: User, Admin

Git graph

gitGraph
  commit id: "init"
  branch develop
  commit
  checkout main
  merge develop
  commit id: "v1.0" tag: "v1.0"
  • Only checkout branches that exist — branch first.
  • commit id: "x" tag: "y" type: REVERSE for highlights.
  • merge develop merges the named branch into the current one.

Quadrant chart

quadrantChart
  title Priorities
  x-axis Low --> High
  y-axis Low --> High
  quadrant-1 Quick wins
  quadrant-2 Big bets
  quadrant-3 Fill-ins
  quadrant-4 Time sinks
  "Search": [0.7, 0.8]
  • Both axes required: x-axis Low --> High.
  • Four quadrant-N labels come before data points.
  • Points: "Name": [x, y] with values 0.0-1.0.

Common errors and fixes

SymptomCauseFix
Nothing renders at all The first line does not declare a diagram type. Start with the declaration: flowchart TD, sequenceDiagram, erDiagram, gantt, pie, mindmap, stateDiagram-v2, classDiagram, journey, timeline, gitGraph or quadrantChart.
"Parse error" pointing at an arrow Misspelled or mixed-up arrow syntax. Valid arrows: -->, ---, -.->, ==>, -->|label|. In sequence diagrams use ->> and -->>.
Node label breaks the diagram Unquoted special characters — parentheses, brackets, colons or commas end the label early. Wrap the label in quotes: A["Deploy (prod)"].
Two nodes merge into one Duplicate node ids. Every id must be unique; give each node its own id and put display text in brackets.
subgraph never closes Missing end keyword. Close every subgraph block with its own end on a separate line.
Sequence diagram: unknown participant A message references a participant that was never declared. Declare participants/actors at the top: participant S as Server.
Sequence diagram: activation error Unbalanced + and - activation markers. Every A->>+B needs a matching B-->>-A. Count them.
Gantt: dates render wrong dateFormat does not match the task dates. Add dateFormat YYYY-MM-DD at the top and write dates as 2026-01-05.
Pie chart: values ignored Values are not plain numbers or labels are unquoted. Use "Label" : 45 — quote labels containing spaces or punctuation.
Mindmap: hierarchy is flat Inconsistent indentation, or tabs mixed with spaces. Indent children with spaces only, deeper than the parent line.
GitGraph: checkout fails Checking out a branch that does not exist yet. Create it first: branch develop, then checkout develop.
Quadrant chart: points missing Missing axis or quadrant declarations. Declare x-axis, y-axis and all four quadrant-N lines before listing points.