Mermaid Diagrams
Overview
Mermaid is a JavaScript-based diagramming tool that renders Markdown-inspired text definitions into SVG diagrams. It supports flowcharts, sequence diagrams, ER diagrams, class diagrams, state diagrams, Gantt charts, pie charts, mindmaps, and git graphs directly inside Markdown files.
When to use: Documenting system architecture, visualizing data models, illustrating request flows, creating project timelines, embedding diagrams in GitHub/GitLab READMEs or docs sites.
When NOT to use: Pixel-perfect design mockups, interactive dashboards, diagrams requiring custom artwork or complex spatial layouts beyond hierarchical/relational structures.
Quick Reference
| Diagram | Declaration | Key Points |
|---|---|---|
| Flowchart | flowchart TD | Directions: TB, TD, BT, RL, LR. Supports subgraphs |
| Sequence | sequenceDiagram | Participants, messages, loops, alt/opt/par blocks |
| ER Diagram | erDiagram | Crow's foot notation, PK/FK/UK attributes |
| Class Diagram | classDiagram | UML relationships, visibility modifiers, annotations |
| State Diagram | stateDiagram-v2 | Transitions, composite states, forks/joins, choice |
| Gantt Chart | gantt | Sections, tasks with dates/durations, milestones |
| Pie Chart | pie | Labels with numeric values, optional title |
| Mindmap | mindmap | Indentation-based hierarchy, multiple node shapes |
| Git Graph | gitGraph | Commits, branches, merges, cherry-picks, tags |
| Architecture | architecture-beta | Services in groups, directional edges (T/B/L/R) |
| Block Diagram | block-beta | Column layout, block arrows, nested blocks |
| Timeline | timeline | Time periods with events, sections for grouping |
| Sankey | sankey-beta | Flow quantities between nodes, CSV-like data format |
| XY Chart | xychart-beta | Bar and line charts with x/y axes |
| Quadrant Chart | quadrantChart | Four-quadrant plot with labeled axes and data points |
| Kanban | kanban | Columns with task cards, assignees, priorities |
| Packet | packet-beta | Network packet structure with bit-range fields |
| Requirement | requirementDiagram | Requirements, elements, and verification links |
| C4 Diagram | C4Context | C4 model: Context, Container, Component, Deployment |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
Using graph instead of flowchart | Use flowchart for subgraph edges and newer features |
| Missing space after arrow in sequences | Alice->>Bob: msg not Alice->>Bob:msg |
| Wrong cardinality order in ER diagrams | Left cardinality, then line, then right cardinality |
Forgetting end after subgraph/loop/alt | Every block keyword requires a matching end |
| Using reserved words as node IDs | Wrap reserved words in quotes or use aliases |
| Bare code blocks without language tag | Always use ``` `mermaid ``` as the language specifier |
| Mixing v1 and v2 state diagram syntax | Use stateDiagram-v2 consistently for current features |
| Unquoted labels with special characters | Wrap labels containing special characters in double quotes |
Missing dateFormat in Gantt charts | Always declare dateFormat before task definitions |
| Using tabs instead of spaces for mindmaps | Mindmap indentation requires spaces, not tabs |
Delegation
- Diagram discovery and exploration: Use
Exploreagent to find existing diagrams in the codebase - Diagram review: Use
Taskagent to verify diagram accuracy against code - Architecture documentation: Use
code-revieweragent for doc quality checks
References
- Flowcharts: nodes, edges, subgraphs, directions, and styling
- Sequence diagrams: participants, messages, activations, and control flow
- Entity-relationship diagrams: entities, attributes, and cardinality
- Class diagrams: classes, methods, relationships, and annotations
- Other diagrams: Gantt, pie, mindmap, state, and git graph
- Architecture, block, timeline, Sankey, XY chart, quadrant, kanban, packet, requirement, and C4 diagrams