Mermaid.js lets you generate diagrams from text. Instead of dragging boxes in a visual editor, you write a few lines of syntax and get a rendered diagram. This makes diagrams version-controllable, easy to embed in markdown, and fast to update. Here's a practical reference for the most useful diagram types.
Flowcharts
The most common Mermaid diagram. Define nodes and connections:
flowchart TD
A[Start] --> B{Is it valid?}
B -- Yes --> C[Process request]
B -- No --> D[Show error]
C --> E[Return response]
D --> E
Node shapes are determined by the brackets:
[Text]— Rectangle{Text}— Diamond (decision)(Text)— Rounded rectangle(((Text)))— Circle[/Text/]— Parallelogram (input/output)
Directions: TD (top-down), LR (left-right), BT (bottom-up), RL (right-left).
Sequence Diagrams
sequenceDiagram
participant C as Client
participant S as Server
participant D as Database
C->>S: GET /api/users
S->>D: SELECT * FROM users
D-->>S: Return rows
S-->>C: 200 OK + JSON
Note over C,S: Response cached for 5 min
Arrow types: ->> (solid), -->> (dashed), -x (solid with X), --x (dashed with X). Use autonumber at the top to add sequence numbers automatically.
ER Diagrams
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
CUSTOMER {
int id PK
string name
string email
}
ORDER {
int id PK
int customer_id FK
date order_date
}
Relationship cardinality: ||--|| (one-to-one), ||--o{ (one-to-many, optional), }o--o{ (many-to-many).
State Diagrams
stateDiagram-v2
[*] --> Idle
Idle --> Loading : user clicks
Loading --> Success : data received
Loading --> Error : timeout
Error --> Idle : retry
Success --> [*]
Class Diagrams
classDiagram
class Animal {
+String name
+int age
+makeSound() void
}
class Dog {
+String breed
+fetch() void
}
Animal <|-- Dog
Visibility: + public, - private, # protected. Relationships: <|-- inheritance, *-- composition, o-- aggregation.
Gantt Charts
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Design
Research :done, a1, 2026-01-01, 7d
Wireframes :a2, after a1, 5d
section Development
Backend :a3, after a2, 14d
Frontend :a4, after a2, 10d
Tips for Readable Diagrams
- Keep node labels short — 2-4 words. Longer labels make diagrams cluttered.
- Use consistent naming (all camelCase or all snake_case).
- Limit flowcharts to 15-20 nodes. If you need more, split into sub-diagrams.
- Add
classDefstyles to highlight important nodes with colour. - Use
subgraphto group related nodes in flowcharts.
The diagram tool on this site renders Mermaid syntax in real time. Paste your code, and see the diagram instantly. Everything runs in your browser — no server, no data upload. Export as SVG when you're ready to use the diagram in documentation.