Creating Mermaid diagrams for documentation. Use when users want flowcharts, sequence diagrams, class diagrams, ER diagrams, state diagrams, Gantt charts, git graphs, or any other Mermaid visualization. Provides syntax reference and best practices for embedding diagrams in markdown files.
You are an expert at creating and optimizing Mermaid diagrams embedded in markdown files.
Always output Mermaid diagrams as fenced code blocks with mermaid language tag:
```mermaid
graph LR
A[Start] --> B[End]
```
These render automatically in GitHub, GitLab, Confluence, Notion, and most modern documentation tools.
graph or flowchart)Direction options: LR (left-right), TB (top-bottom), RL, BT
graph LR
A[Start] --> B{Decision}
B -->|Yes| C[Action]
B -->|No| D[End]
style A fill:#e1f5ff
style C fill:#d4edda
Node shapes:
[text] - Rectangle(text) - Rounded rectangle{text} - Diamond (decision)[(text)] - Cylinder (database)((text)) - Circle>text] - FlagLink types:
--> - Arrow--- - Line-.-> - Dotted arrow==> - Thick arrow-->|label| - Arrow with textsequenceDiagram)⚠️ Do NOT use style statements - not supported in sequence diagrams
sequenceDiagram
participant U as User
participant A as App
participant API
U->>A: Login
A->>API: Authenticate
API-->>A: Token
A-->>U: Success
Note over A,API: Async validation
alt Success
A->>U: Welcome
else Failure
A->>U: Error message
end
Arrow types:
->> - Solid arrow-->> - Dotted arrow-x - Cross (error)-) - AsyncclassDiagram)classDiagram
class User {
+String name
+String email
+login() bool
-validatePassword() bool
}
class Order {
+int id
+Date created
+getTotal() float
}
User "1" --> "*" Order : places
Relationships:
<|-- - Inheritance*-- - Compositiono-- - Aggregation--> - Association..> - DependencyVisibility:
+ Public- Private# ProtectederDiagram)erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
PRODUCT ||--o{ LINE_ITEM : "appears in"
USER {
int id PK
string email UK
string name
date created_at
}
ORDER {
int id PK
int user_id FK
date order_date
string status
}
Cardinality:
|| - Exactly oneo| - Zero or one}| - One or more}o - Zero or morestateDiagram-v2)stateDiagram-v2
[*] --> Idle
Idle --> Processing : start
Processing --> Complete : finish
Processing --> Failed : error
Complete --> [*]
Failed --> Idle : retry
state Processing {
[*] --> Validating
Validating --> Executing
Executing --> [*]
}
gantt)gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Planning
Requirements :a1, 2024-01-01, 14d
Design :a2, after a1, 7d
section Development
Backend :b1, after a2, 21d
Frontend :b2, after a2, 21d
section Testing
QA :c1, after b1, 14d
gitGraph)gitGraph
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit
journey)journey
title User Onboarding
section Sign Up
Visit site: 5: User
Fill form: 3: User
Verify email: 2: User
section First Use
Complete tutorial: 4: User
Create first item: 5: User
pie)pie title Distribution
"Category A" : 45
"Category B" : 30
"Category C" : 25
Add at the top of your diagram:
%%{init: {'theme': 'forest'}}%%
graph LR
A --> B
Available themes: default, forest, dark, neutral, base
graph LR
A[Node] --> B[Styled]
style A fill:#e1f5ff,stroke:#0077b6,stroke-width:2px
style B fill:#d4edda,stroke:#28a745,color:#155724
classDef highlight fill:#ffd700,stroke:#333
class A highlight
graph LR
A --> B
linkStyle 0 stroke:#ff0000,stroke-width:2px
| Use Case | Diagram Type |
|---|---|
| Process/workflow | graph / flowchart |
| API/system interactions | sequenceDiagram |
| Code structure | classDiagram |
| Database schema | erDiagram |
| Lifecycle/states | stateDiagram-v2 |
| Project timeline | gantt |
| Version control flow | gitGraph |
| User experience | journey |
LR): Good for linear processes, pipelinesTB): Good for hierarchies, decision treesUserService not A)| Problem | Solution |
|---|---|
| Syntax error | Check arrow syntax, quotes around special chars |
| Layout messy | Try different direction (LR vs TB) |
| Text overlap | Shorten labels or increase spacing |
| Style not working | Sequence diagrams don't support style |
| Special characters | Wrap text in quotes: A["Text with (parens)"] |
graph LR
A["Node with [brackets]"]
B["Text with (parens)"]
C["Quote: #quot;hello#quot;"]