AHA Mermaid Diagram
Render Mermaid.js class, flowchart, sequence, and ER diagrams in HTML with live preview, dark theme, and error handling for clean visualization.
Aha Mermaid Diagram Expert
Professional Mermaid.js diagrams for software architecture, domain modeling, and system visualization.
Installation
CDN (HTML)
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
<pre class="mermaid">
flowchart LR
A --> B
</pre>
CLI Export
npm install -g @mermaid-js/mermaid-cli
mmdc -i input.mmd -o output.png -w 1920 -H 1080
Core Syntax
All Mermaid diagrams:
diagramType
definition content
Key principles:
- First line declares type:
classDiagram,sequenceDiagram,flowchart,erDiagram,C4Context,stateDiagram,gantt - Use
%%for comments - Line breaks improve readability
- Unknown words break diagrams; invalid parameters fail silently
- Avoid
{}in comments
Diagram Type Selection
| Type | Use For | Best Practice |
|---|---|---|
| Class Diagram | Domain modeling, OOP design, entity relationships | Show attributes + methods |
| Sequence Diagram | API flows, auth flows, component interactions | Use activations, autonumber |
| Flowchart | Processes, algorithms, decision trees, user journeys | Keep <15 nodes per diagram |
| ERD | Database schemas, table relationships | UPPERCASE entity names |
| C4 Diagrams | System context, containers, components, architecture | 4 levels: Context→Container→Component→Code |
| State Diagram | State machines, lifecycle states | Use choice nodes for transitions |
| Git Graphs | Branching strategies | Show merges clearly |
| Gantt Charts | Project timelines, scheduling | Group by category |
Class Diagram (Domain Model)
Visibility modifiers: + public, - private, # protected, ~ package
Relationships:
--Association (loose relationship)*--Composition (strong ownership, child dies with parent)o--Aggregation (weak ownership, child can exist alone)<|--Inheritance ("is-a")<..Dependency (parameter/local variable)<|..Implementation (interface)
Sequence Diagram (API Flow)
Message types: ->> solid request, -->> dotted response, -) async
Structures: alt/else/end, opt, par/and/end, loop, break
Tips: Use activations (+/-), autonumber, descriptive notes
Flowchart (Process/Decision)
Directions: TD/TB (top-down), BT (bottom-up), LR (left-right), RL (right-left)
Node shapes:
[Text]Rectangle([Text])Stadium/pill[[Text]]Subroutine[(Text)]Cylinder (database)((Text))Circle{Text}Rhombus (decision){{Text}}Hexagon[/Text/]Parallelogram (IO)[>Text]Asymmetric/flag
Connections: --> arrow, --- open, -.-> dotted, ==> thick
ERD (Database Schema)
Cardinality: || exactly one, |o zero or one, }{ one or many, }o zero or many
Constraints: PK (primary key), FK (foreign key), UK (unique), NN (not null)
C4 Architecture Diagrams
Levels: C4Context → C4Container → C4Component → Class diagrams
Elements: Person, System, System_Ext, SystemDb, SystemQueue, Container, ContainerDb, ContainerQueue, Component
Advanced Configuration
Theme Variables
mermaid.initialize({
theme: 'dark',
themeVariables: {
primaryColor: '#3b82f6',
primaryTextColor: '#f1f5f9',
primaryBorderColor: '#8b5cf6',
lineColor: '#06b6d4',
background: '#111827',
mainBkg: '#1e293b'
}
});
Available themes: default, forest, dark, neutral, base
Layout Options
// Dagre (default) - balanced layout
// ELK - better for complex diagrams
mermaid.initialize({
layout: 'elk',
elk: {
mergeEdges: true,
nodePlacementStrategy: 'BRANDES_KOEPF'
}
});
Look Options
mermaid.initialize({
look: 'classic' // Traditional
// or
look: 'handDrawn' // Sketch-like
});
HTML Rendering Config
mermaid.initialize({
startOnLoad: false,
maxTextSize: 99999,
fontSize: 14,
securityLevel: 'loose'
});
Styling
Node Styling
Link Styling
Subgraph Styling
Interactive Features
Click Events & Links
Tooltips
Export Options
| Method | Command |
|---|---|
| Live Editor | https://mermaid.live |
| CLI PNG | mmdc -i diagram.mmd -o output.png |
| CLI SVG | mmdc -i diagram.mmd -o output.svg |
| Custom Size | mmdc -i input.mmd -o output.png -w 1920 -H 1080 |
| Dark BG | mmdc -i input.mmd -o output.svg -b "#111827" |
HTML Template
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Mermaid Diagram</title>
<style>
body { margin: 0; background: #111827; }
.mermaid { display: flex; justify-content: center; padding: 20px; }
.mermaid svg { max-width: 100%; height: auto; }
</style>
</head>
<body>
<div class="mermaid">
flowchart LR
A[Start] --> B[Process] --> C[End]
</div>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({
startOnLoad: true,
theme: 'dark',
themeVariables: {
primaryColor: '#3b82f6',
background: '#111827',
mainBkg: '#1e293b',
fontSize: '14px'
}
});
</script>
</body>
</html>
Best Practices
- Start simple — begin with core entities, add details incrementally
- Use meaningful names — clear labels make diagrams self-documenting
- Comment extensively — use
%%comments to explain complex relationships - Keep focused — one diagram per concept; split large diagrams
- Version control — store
.mmdfiles alongside code - Add context — include titles and notes to explain purpose
- Iterate — refine diagrams as understanding evolves
Common Pitfalls
| Error | Cause | Solution |
|---|---|---|
Nodes undefined | Chinese class names | Use English identifiers |
No diagram type | Syntax error | Validate in mermaid.live |
| Diagram too small | Missing config | Set useMaxWidth: false |
Mermaid not defined | Load order | Use waitForMermaid() |
| Lines crossing | Complex layout | Use ELK layout |
| Truncated text | Too many nodes | Split into multiple diagrams |
NEVER Do
- NEVER create diagrams with >15 nodes — unreadable; split into focused views
- NEVER leave arrows unlabeled — every connection should explain the relationship
- NEVER create diagrams without a title — context-free diagrams are useless
- NEVER use diagrams as sole documentation — pair with prose explaining the "why"
- NEVER let diagrams go stale — update when architecture changes
- NEVER use Mermaid for data visualization — it's for architecture, not charts
Quick Reference
Entity with Methods Template
Complete Relationship Set
Flowchart Complete Shapes
Related skills
- Downloads
- 1kAll time
- Security audit
- Pass
- Last updated
- 6mo ago
- Current version
- v1.1.0
- License
- MIT-0
