2026-10-02
Mermaid turns plain text into diagrams, and every diagram starts with a keyword that names its type. This sheet has the syntax you reach for most, with a snippet for each type you can paste straight into the Mermaid Diagram Editor - or into the Sequence Diagram Generator for the sequence examples - to see it render live.
The first line of the text picks the diagram type. Get it wrong and nothing renders.
| Diagram | First line |
|---|---|
| Flowchart | flowchart TD (or flowchart LR) |
| Sequence diagram | sequenceDiagram |
| Class diagram | classDiagram |
| ER diagram | erDiagram |
| State diagram | stateDiagram-v2 |
| Gantt chart | gantt |
The direction after flowchart sets the layout: TD / TB (top to bottom), BT, LR (left to right), or RL. Use LR for wide pipelines and TD for decision trees.
flowchart TD
A[Start] --> B{Is it working?}
B -- Yes --> C[Ship it]
B -- No --> D[Debug]
D --> B
Node shapes
| Syntax | Shape |
|---|---|
A[Text] |
Rectangle |
A(Text) |
Rounded rectangle |
A([Text]) |
Stadium (pill) |
A[(Text)] |
Cylinder (database) |
A((Text)) |
Circle |
A{Text} |
Diamond (decision) |
A{{Text}} |
Hexagon |
Link types
| Syntax | Meaning |
|---|---|
A --> B |
Arrow |
A --- B |
Line with no arrowhead |
A -- text --> B |
Arrow with a label |
A -.-> B |
Dotted arrow |
A ==> B |
Thick arrow |
A --> B & C |
One source to several targets |
Group related nodes with a subgraph:
flowchart LR
subgraph Backend
API --> DB[(Database)]
end
Client --> API
Messages are drawn in the order you write them, top to bottom. Declare participants first to control their left-to-right order and display names.
sequenceDiagram
participant C as Client
participant A as API
participant D as DB
C->>A: POST /login
A->>D: SELECT user WHERE email = ?
D-->>A: user row
A-->>C: 200 OK + session token
| Arrow | Meaning |
|---|---|
->> |
Solid line, arrowhead (a call or request) |
-->> |
Dashed line, arrowhead (a reply or response) |
-) |
Solid line, open arrow (async message) |
-x |
Solid line ending in a cross (lost or failed message) |
Useful blocks: alt / else / end for branches, loop / end for repetition, opt / end for optional steps, and Note right of A: text for annotations. Add autonumber on its own line after sequenceDiagram to number every message.
sequenceDiagram
autonumber
Client->>API: GET /orders
alt cache hit
API-->>Client: 200 (cached)
else cache miss
API->>DB: query
DB-->>API: rows
API-->>Client: 200
end
Members go under the class name. Prefix with + (public), - (private), # (protected), or ~ (package). Methods have parentheses; fields do not.
classDiagram
class Animal {
+String name
+int age
+eat() void
}
class Dog {
+bark() void
}
Animal <|-- Dog
Dog "1" --> "*" Toy : plays with
| Syntax | Relationship |
|---|---|
A <|-- B |
Inheritance (B extends A) |
A *-- B |
Composition (B cannot exist without A) |
A o-- B |
Aggregation (B can exist on its own) |
A --> B |
Association |
A ..> B |
Dependency |
A ..|> B |
Realization (A implements interface B) |
Entities are linked by relationships plus optional attribute blocks. The line between them encodes cardinality on each end.
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
CUSTOMER {
int id PK
string email UK
string name
}
ORDER {
int id PK
int customer_id FK
date placed_on
}
| Marker | Meaning |
|---|---|
|| |
Exactly one |
o| |
Zero or one |
}o / o{ |
Zero or many |
}| / |{ |
One or many |
Read CUSTOMER ||--o{ ORDER as "one customer places zero or many orders". A solid line (--) is an identifying relationship; a dashed line (..) is non-identifying.
Use stateDiagram-v2. [*] is the start state when it is the source of an arrow and the end state when it is the target.
stateDiagram-v2
[*] --> Idle
Idle --> Loading : fetch
Loading --> Success : 200
Loading --> Error : failure
Error --> Loading : retry
Success --> [*]
Add a nested state with state Name { ... }, a fork or join with state fork_state <<fork>>, and a note with note right of Idle followed by text and end note.
Set the date format once, then list tasks under sections. Each task is Name : id, start, duration - the start can be a date or after otherId.
gantt
title Launch plan
dateFormat YYYY-MM-DD
section Build
Design :done, des, 2026-10-01, 5d
Implement :active, imp, after des, 10d
section Ship
QA : qa, after imp, 4d
Release :milestone, rel, after qa, 0d
Status tags go first in the task's settings: done, active, crit (highlight as critical), or milestone. Durations use d (days), w (weeks), h (hours).
end (lowercase) breaks flowcharts - write End or wrap it, e.g. A["end"]. An id starting with o or x right after --- can be read as a circle or cross edge, so add a space or capitalize.A["Save (draft)"].<br/> inside a quoted label, not a literal newline.%% to leave a comment that is ignored.alt blocks, and class bodies must be closed with their matching end or }.