Mermaid Diagram Syntax
Scope
Use when constructing, selecting, or debugging Mermaid syntax. Choose the diagram family that best expresses the intended semantics, then load only the relevant reference below. This skill covers Mermaid construction and parser/rendering constraints; it does not define the process/system being represented.
Workflow
flowchart TD
Start([Task received]) --> Q1{Diagram type?}
Q1 -->|flowchart/graph| FC[Load node-shapes.md + edge-syntax.md]
Q1 -->|sequence| SEQ[Load sequence-diagram.md]
Q1 -->|class| CLS[Load class-diagram.md]
Q1 -->|state| ST[Load state-diagram.md]
Q1 -->|er| ER[Load er-diagram.md]
Q1 -->|gantt| GNT[Load gantt.md]
Q1 -->|gitGraph| GIT[Load git-graph.md]
Q1 -->|mindmap| MM[Load mindmap.md]
Q1 -->|timeline/journey| TL[Load timeline-journey.md]
Q1 -->|pie/quadrant/XY/sankey| DC[Load data-charts.md]
Q1 -->|block/C4/kanban/packet| ADV[Load advanced-diagrams.md]
Q1 -->|fix broken syntax| Debug["Identify diagram family and failing construct; load only references that govern it"]
FC --> Construct[Construct diagram using syntax reference]
SEQ --> Construct
CLS --> Construct
ST --> Construct
ER --> Construct
GNT --> Construct
GIT --> Construct
MM --> Construct
TL --> Construct
DC --> Construct
ADV --> Construct
Debug --> Construct
Reference Files
Load only references needed by the current diagram branch.
Flowchart References
Node Shapes — Load for node syntax or shape selection.
Edge Syntax — Load for connections, labels, edge types, or edge styling.
Subgraphs and Layout — Load for grouping, layout, direction, or escaping.
Styling and Configuration — Load for styling, configuration, renderer, or interactivity.
Flowchart Construction — Load when choosing flowchart elements from scratch.
Other Diagram Types
Sequence Diagram — Actors, messages, loops, alt/opt/par blocks, activations, notes, and autonumbering. Load when constructing sequence diagrams.
Class Diagram — Classes, attributes, methods, visibility, relationships (inheritance, composition, aggregation, dependency), and namespaces. Load when constructing class diagrams.
State Diagram — States, transitions, composite states, fork/join, concurrency, and notes. Load when constructing state diagrams.
ER Diagram — Entities, attributes, relationship cardinality, and keys. Load when constructing entity-relationship diagrams.
Gantt — Tasks, sections, dependencies, date formats, exclusions, and milestones. Load when constructing gantt charts.
Timeline and Journey — Timeline events with dates and sections; user journey tasks with scores and actors. Load when constructing timeline or user journey diagrams.
Git Graph — Commits, branches, merges, cherry-picks, tags, and theme variables. Load when constructing git graph diagrams.
Mindmap — Root nodes, child nodes, icons, classes, and shapes. Load when constructing mindmap diagrams.
Data Charts — Pie charts, quadrant charts, XY charts, and sankey diagrams. Load when constructing data visualization diagrams.
Advanced Diagrams — Block diagrams, C4 architecture diagrams, kanban boards, and packet diagrams. Load when constructing advanced or specialized diagram types.
Critical Constraints
- The word
end in all lowercase breaks flowcharts — capitalize as End or END
- Starting a node connection with
o or x creates circle/cross edges — add a space or capitalize
- Subgraph direction is ignored when any subgraph node links to an external node
- Click interactivity requires
securityLevel='loose' — disabled in strict mode
- Commas in
stroke-dasharray must be escaped as \, in classDef statements
References
[1] Mermaid Flowchart Syntax Documentation (accessed 2026-03-07)
[2] Mermaid Official Site — Flowchart Syntax (accessed 2026-03-07)