Mermaid Diagram Guide
Mermaid is a JavaScript-based diagramming tool that lets you create diagrams and visualizations using text-based syntax inside Markdown code blocks. Instead of dragging shapes around in a design tool, you describe your diagram with simple text, and it renders automatically. Mermaid supports flowcharts, sequence diagrams, class diagrams, Gantt charts, ER diagrams, state diagrams, pie charts, and more.
How to Use Mermaid in Markdown
Wrap your Mermaid code in a fenced code block with the mermaid language identifier:
```mermaid
graph TD
A[Start] --> B[Process]
B --> C[End]
```This works in MD Viewer, GitHub, GitLab, Notion, and many other Markdown renderers. MD Viewer renders Mermaid diagrams in real-time as you type.
Flowcharts
Flowcharts are the most common Mermaid diagram. They show processes, decisions, and connections between steps.
Direction
Set the direction with graph or flowchart followed by a direction keyword:
| Direction | Keyword | Description |
|---|---|---|
| Top to Bottom | TD or TB | Default vertical flow |
| Bottom to Top | BT | Reverse vertical flow |
| Left to Right | LR | Horizontal flow |
| Right to Left | RL | Reverse horizontal flow |
Node Shapes
```mermaid
flowchart LR
A[Rectangle]
B(Rounded)
C([Stadium])
D[[Subroutine]]
E[(Database)]
F((Circle))
G{Diamond}
H{{Hexagon}}
I[/Parallelogram/]
J[\Parallelogram alt\]
K[/Trapezoid\]
```Link Types
```mermaid
flowchart LR
A --> B %% Arrow
C --- D %% Line (no arrow)
E -.- F %% Dotted line
G -.-> H %% Dotted arrow
I ==> J %% Thick arrow
K -- "label" --> L %% Arrow with label
M -->|label| N %% Alternative label syntax
```Complete Flowchart Example
```mermaid
flowchart TD
Start([Start]) --> Input[/Get user input/]
Input --> Validate{Is input valid?}
Validate -->|Yes| Process[Process data]
Validate -->|No| Error[Show error message]
Error --> Input
Process --> Save[(Save to database)]
Save --> End([End])
```Subgraphs
Group related nodes together:
```mermaid
flowchart TB
subgraph Frontend
A[React App] --> B[API Client]
end
subgraph Backend
C[Express Server] --> D[(PostgreSQL)]
end
B --> C
```Sequence Diagrams
Show interactions between actors or systems over time. Ideal for documenting API flows, authentication sequences, or microservice communication.
```mermaid
sequenceDiagram
participant U as User
participant C as Client
participant S as Server
participant DB as Database
U->>C: Click login button
C->>S: POST /auth/login
S->>DB: Query user credentials
DB-->>S: User record
alt Valid credentials
S-->>C: 200 OK + JWT token
C-->>U: Show dashboard
else Invalid credentials
S-->>C: 401 Unauthorized
C-->>U: Show error message
end
```Message Arrow Types
| Arrow | Description |
|---|---|
->> | Solid line with arrowhead |
-->> | Dashed line with arrowhead |
-> | Solid line without arrowhead |
--> | Dashed line without arrowhead |
-x | Solid line with cross (async) |
--x | Dashed line with cross (async) |
Sequence Features
```mermaid
sequenceDiagram
participant A
participant B
Note over A,B: Authentication Flow
A->>B: Request
activate B
B-->>A: Response
deactivate B
loop Every 30 seconds
A->>B: Heartbeat ping
end
opt Optional step
A->>B: Extra request
end
```Class Diagrams
Describe object-oriented structures with classes, attributes, methods, and relationships:
```mermaid
classDiagram
class Animal {
+String name
+int age
+makeSound() void
+move() void
}
class Dog {
+String breed
+fetch() void
+bark() void
}
class Cat {
+bool isIndoor
+purr() void
+scratch() void
}
Animal <|-- Dog : inherits
Animal <|-- Cat : inherits
Dog "1" --> "*" Toy : plays with
```Relationship Types
| Syntax | Relationship |
|---|---|
<|-- | Inheritance |
*-- | Composition |
o-- | Aggregation |
--> | Association |
..> | Dependency |
..|> | Realization (implements) |
Gantt Charts
Visualize project timelines, task dependencies, and milestones:
```mermaid
gantt
title Project Development Timeline
dateFormat YYYY-MM-DD
excludes weekends
section Planning
Requirements gathering :done, req, 2025-01-06, 5d
Technical design :done, des, after req, 3d
Architecture review :milestone, m1, after des, 0d
section Development
Backend API :active, api, after des, 10d
Frontend UI :ui, after des, 12d
Integration :int, after api, 5d
section Testing
Unit tests :test1, after api, 5d
E2E tests :test2, after int, 4d
UAT :uat, after test2, 3d
section Deployment
Production release :milestone, m2, after uat, 0d
```Entity Relationship Diagrams
Model database schemas and their relationships:
```mermaid
erDiagram
USER ||--o{ ORDER : places
USER {
int id PK
string name
string email UK
date created_at
}
ORDER ||--|{ LINE_ITEM : contains
ORDER {
int id PK
int user_id FK
date order_date
string status
}
PRODUCT ||--o{ LINE_ITEM : "is in"
PRODUCT {
int id PK
string name
decimal price
int stock
}
LINE_ITEM {
int id PK
int order_id FK
int product_id FK
int quantity
}
```Cardinality Notation
| Syntax | Meaning |
|---|---|
||--|| | One to one |
||--o{ | One to zero or more |
||--|{ | One to one or more |
}o--o{ | Zero or more to zero or more |
State Diagrams
Model state machines and lifecycle transitions:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Review : Submit
Review --> Approved : Approve
Review --> Draft : Request changes
Approved --> Published : Publish
Published --> Archived : Archive
Archived --> [*]
state Review {
[*] --> PeerReview
PeerReview --> TechLead
TechLead --> [*]
}
```Pie Charts
Simple data visualization for proportional data:
```mermaid
pie title Browser Market Share (2025)
"Chrome" : 65
"Safari" : 19
"Firefox" : 4
"Edge" : 5
"Other" : 7
```Tips for Better Diagrams
- Keep it simple — If your diagram has more than 15-20 nodes, consider splitting it into multiple diagrams.
- Use meaningful IDs — Name nodes descriptively (
AuthServicenotA) for readable source. - Direction matters — Use LR for process flows, TD for hierarchies.
- Add comments — Use
%%for comments that won't render:%% This is a comment - Use subgraphs — Group related nodes to add visual structure.
- Label relationships — Always label edges in ER and class diagrams for clarity.
Build diagrams visually — Use our dedicated Mermaid editor with live preview and syntax hints.
Open Mermaid Editor