What is Mermaid?
Mermaid is a text-based diagramming and charting tool that renders diagrams from markdown-like text. Perfect for:
- Documentation — Embed diagrams in README, wikis, and docs
- Presentations — Generate diagrams on the fly
- Version control — Diagrams are text, so they diff nicely
- Collaboration — Easy to edit and review
Supported diagram types:
- Flowcharts
- Sequence diagrams
- Class diagrams
- Gantt charts
- State diagrams
- Entity-relationship diagrams
- Git graphs
- Pie charts
Installation & Setup
GitHub/GitLab (Built-in Support)
Both GitHub and GitLab render Mermaid diagrams automatically:
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action]
B -->|No| D[End]
```
Visual Studio Code
Install the Markdown Preview Mermaid Support extension:
- Open VS Code Extensions (Ctrl+Shift+X)
- Search for "Markdown Preview Mermaid Support"
- Install and reload
Local Rendering
# Install Mermaid CLI
npm install -g @mermaid-js/mermaid-cli
# Generate PNG from Mermaid file
mmdc -i diagram.mmd -o diagram.png
# Generate SVG
mmdc -i diagram.mmd -o diagram.svg -t dark
Online Editor
Use Mermaid Live Editor for quick prototyping and sharing.
Flowcharts
Flowcharts are the most common diagram type. Use for decision trees, processes, and workflows.
Basic Syntax
```mermaid
graph TD
A[Start] --> B{Is it working?}
B -->|Yes| C[Great!]
B -->|No| D[Debug]
D --> B
C --> E[End]
```
Node Shapes
graph LR
A[Rectangle]
B(Rounded Rectangle)
C([Stadium Shape])
D[[Subroutine]]
E[(Cylinder)]
F([Circle])
G((Circle Double))
H>Asymmetric Shape]
I{Rhombus}
J
K[/Parallelogram/]
L[\Parallelogram Alt\]
M[/Trapezoid\]
N[\Trapezoid Alt/]
Direction
TD/TB— Top to bottom (default)BT— Bottom to topLR— Left to rightRL— Right to left
Styling
```mermaid
graph TD
A[Default] --> B[Styled]
B --> C[Another Style]
style B fill:#f9f,stroke:#333,stroke-width:4px
style C fill:#bbf,stroke:#333,stroke-width:2px,color:#fff
```
Subgraphs
```mermaid
graph TD
A[Start] --> B[Process A]
B --> subgraph1[Subgraph 1]
B --> subgraph2[Subgraph 2]
subgraph subgraph1[Subgroup 1]
C[Task C]
D[Task D]
C --> D
end
subgraph subgraph2[Subgroup 2]
E[Task E]
F[Task F]
E --> F
end
```
Sequence Diagrams
Sequence diagrams show interactions between objects over time.
Basic Syntax
```mermaid
sequenceDiagram
participant A as Client
participant B as Server
participant C as Database
A->>B: HTTP Request
B->>C: Query
C-->>B: Results
B-->>A: HTTP Response
```
Arrow Types
->>— Solid line with arrowhead-->>— Dashed line with arrowhead->— Solid line (no arrowhead)-->— Dashed line (no arrowhead)-x— Solid line with cross--x— Dashed line with cross
Activation Boxes
```mermaid
sequenceDiagram
participant A as User
participant B as API
participant C as Service
A->>+B: Request
activate B
B->>+C: Process
activate C
C-->>-B: Response
deactivate C
B-->>-A: Result
deactivate B
```
Notes and Loops
```mermaid
sequenceDiagram
participant A as Client
participant B as Server
loop Every 5 minutes
A->>B: Health Check
alt Server is up
B-->>A: OK (200)
else Server is down
B-->>A: Error (500)
Note over A,B: Retry in 5 minutes
end
end
```
Class Diagrams
Class diagrams show the structure of object-oriented systems.
Basic Syntax
```mermaid
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+String breed
+bark()
}
class Cat {
+bool isIndoor
+meow()
}
Animal <|-- Dog
Animal <|-- Cat
```
Relationships
<|--— Inheritance*--— Compositiono--— Aggregation-->— Association..>— Dependency..|>— Implementation--— Link
Methods Visibility
+— Public-— Private#— Protected~— Package/Internal
Gantt Charts
Gantt charts visualize project timelines and schedules.
Basic Syntax
```mermaid
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Design :a1, 2025-01-01, 30d
Development :a2, after a1, 45d
section Phase 2
Testing :b1, after a2, 20d
Deployment :b2, after b1, 10d
```
Milestones and Dependencies
```mermaid
gantt
title Development Timeline
dateFormat YYYY-MM-DD
section Backend
API Design :2025-01-01, 10d
Implementation :10d
Testing :5d
section Frontend
UI Design :2025-01-05, 15d
Development :20d
section Integration
Integration :crit, after API Testing, 5d
Deployment :milestone, after Integration, 0d
```
State Diagrams
State diagrams show state machines and transitions.
Basic Syntax
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Processing: Start
Processing --> Completed: Success
Processing --> Error: Failure
Error --> Idle: Retry
Completed --> [*]
```
Concurrent States
```mermaid
stateDiagram-v2
[*] --> Active
state Active {
[*] --> NumLockOff
NumLockOff --> NumLockOn: Press NumLock
NumLockOn --> NumLockOff: Press NumLock
--
[*] --> CapsLockOff
CapsLockOff --> CapsLockOn: Press CapsLock
CapsLockOn --> CapsLockOff: Press CapsLock
}
Active --> [*]
```
ER Diagrams
Entity-relationship diagrams model database schemas.
Basic Syntax
```mermaid
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
PRODUCT ||--o{ LINE-ITEM : "ordered in"
CUSTOMER {
string name
string email
int id PK
}
ORDER {
int id PK
date orderDate
int customerId FK
}
PRODUCT {
int id PK
string name
float price
}
LINE-ITEM {
int quantity
int orderId FK
int productId FK
}
```
Relationship Cardinality
||--||— One to one||--o{— One to many}o--o{— Many to many}o--||— Many to one
Git Graphs
Git graphs visualize git branches and commits.
Basic Syntax
```mermaid
gitGraph
commit id: "Initial"
branch develop
checkout develop
commit id: "Feature 1"
commit id: "Feature 2"
checkout main
commit id: "Hotfix"
merge develop
commit id: "Release"
```
Branching Strategies
```mermaid
gitGraph
commit id: "Init"
branch feature/login
checkout feature/login
commit id: "Add login form"
commit id: "Add validation"
checkout main
commit id: "Update docs"
merge feature/login
branch release/v1.0
checkout release/v1.0
commit id: "Prepare release"
checkout main
commit id: "Version bump"
```
Best Practices
1. Keep Diagrams Simple
Avoid overcrowding. Break complex diagrams into multiple smaller ones.
2. Use Descriptive Labels
graph LR
A[User Login Request] --> B{Valid Credentials?}
B -->|Yes| C[Generate JWT Token]
B -->|No| D[Return 401 Error]
3. Consistent Naming
Use consistent naming conventions across diagrams (e.g., camelCase for functions, PascalCase for classes).
4. Version Control
Store Mermaid files in your repository alongside code:
docs/
├── architecture/
│ ├── system-overview.mmd
│ ├── data-flow.mmd
│ └── deployment.mmd
5. Documentation Integration
Embed diagrams directly in documentation:
- README.md — System overview, setup flow
- API docs — Request/response flows
- Architecture docs — Component interactions
Tips & Tricks
Tip 1: Use Comments
```mermaid
graph TD
%% This is a comment
A[Start] --> B[Process]
%% Another comment explaining the flow
B --> C[End]
```
Tip 2: Export Options
# Generate multiple formats
mmdc -i diagram.mmd -o diagram.png -w 1920 -H 1080
mmdc -i diagram.mmd -o diagram.svg -b transparent
mmdc -i diagram.mmd -o diagram.pdf
Tip 3: Dark Theme
```mermaid
%%{init: {'theme':'dark'}}%%
graph TD
A[Start] --> B[End]
```
Tip 4: Custom Themes
// theme.json
{
"theme": "base",
"themeVariables": {
"primaryColor": "#ff0000",
"primaryTextColor": "#fff",
"primaryBorderColor": "#7C0000",
"lineColor": "#F8B229",
"secondaryColor": "#006100",
"tertiaryColor": "#fff"
}
}
mmdc -i diagram.mmd -o diagram.png -t ./theme.json
Tip 5: Combine with Markdown
Here's the system architecture:
```mermaid
graph TD
A[Client] --> B[API Gateway]
B --> C[Services]
```
The API Gateway routes requests to various microservices.
Resources
Need help with documentation or technical writing? Contact us for consulting.