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 Explore agent to find existing diagrams in the codebase
Diagram review: Use Task agent to verify diagram accuracy against code
Architecture documentation: Use code-reviewer agent for doc quality checks

mermaid-diagrams

Mermaid Diagrams

Overview

Quick Reference

Common Mistakes

Delegation

References