Mermaid Syntax Reference
A comprehensive reference for all 23 Mermaid diagram types plus configuration and theming. This skill provides official Mermaid syntax documentation sourced from the mermaid-skill project (auto-synced from upstream Mermaid docs).
This skill ships reference material, not runnable scripts. Read the relevant reference file with Read, apply the syntax, and write the diagram into the user's artefact. Do not Bash-execute anything from references/ — they are Mermaid syntax docs, not commands.
To look up syntax for a specific diagram type, identify the type from the table below and read the corresponding reference file.
Supported Diagram Types
Select the appropriate diagram type and read the corresponding reference file:
| Type |
Reference |
ArcKit Commands Using It |
| Flowchart |
flowchart.md |
$arckit-diagram, $arckit-dfd, $arckit-roadmap, $arckit-plan, $arckit-backlog, $arckit-strategy, $arckit-story, $arckit-jsp-936 |
| Sequence Diagram |
sequenceDiagram.md |
$arckit-diagram |
| Class Diagram |
classDiagram.md |
— |
| State Diagram |
stateDiagram.md |
— |
| ER Diagram |
entityRelationshipDiagram.md |
$arckit-data-model |
| Gantt Chart |
gantt.md |
$arckit-roadmap, $arckit-plan, $arckit-strategy, $arckit-story, $arckit-presentation |
| Pie Chart |
pie.md |
$arckit-story, $arckit-presentation |
| Mindmap |
mindmap.md |
$arckit-story |
| Timeline |
timeline.md |
$arckit-story |
| Git Graph |
gitgraph.md |
— |
| Quadrant Chart |
quadrantChart.md |
$arckit-presentation |
| Requirement Diagram |
requirementDiagram.md |
— |
| C4 Diagram |
c4.md |
$arckit-diagram, $arckit-presentation |
| Sankey Diagram |
sankey.md |
— |
| XY Chart |
xyChart.md |
— |
| Block Diagram |
block.md |
— |
| Packet Diagram |
packet.md |
— |
| Kanban |
kanban.md |
— |
| Architecture Diagram |
architecture.md |
— |
| Radar Chart |
radar.md |
— |
| Treemap |
treemap.md |
— |
| User Journey |
userJourney.md |
— |
| ZenUML |
zenuml.md |
— |
Configuration & Theming
| Topic |
Reference |
| Theming |
config-theming.md |
| Directives |
config-directives.md |
| Layouts |
config-layouts.md |
| Configuration |
config-configuration.md |
| Math |
config-math.md |
| Tidy Tree |
config-tidy-tree.md |
| Examples |
examples.md |
C4 Layout Science
For research-backed C4 diagram layout guidance (declaration ordering, edge crossing targets, colour standards, PlantUML directional hints), see c4-layout-science.md. This ArcKit-specific reference supplements the upstream C4 syntax reference with graph drawing science and layout optimisation techniques.
Common Syntax Gotchas
These are the most common Mermaid syntax errors encountered when generating diagrams:
| Gotcha |
Problem |
Fix |
<br/> in flowchart edge labels |
Mermaid flowchart parser rejects HTML in edge labels |
Use comma-separated text: -->|"Uses, HTTPS"| |
end as node ID |
end is a reserved keyword in Mermaid |
Use a different ID: EndNode["End"] |
| Gantt date formats |
Gantt requires specific date format |
Use YYYY-MM-DD (e.g., 2025-01-15) |
| Gantt task status |
Invalid task status keywords |
Valid: done, active, crit, milestone |
| Parentheses in labels |
Unescaped () breaks node parsing |
Wrap in quotes: Node["Label (with parens)"] |
| Special chars in IDs |
Hyphens, dots, spaces in node IDs |
Use camelCase or underscores: apiGateway, api_gateway |
| ER combined keys |
FK UK (space-separated) and PK_FK are parse errors, and the whole block silently fails to render |
Comma-separate them: uuid tenant_id FK, UK |
| ER attribute comments |
An unclosed ", or a " inside the comment, breaks the block |
One pair of double quotes, last on the line, no " inside |
| ER cardinality tokens |
Invented tokens (e.g. ||--x{) fail to parse |
Left: || |o }o }| — right: || o| o{ |{ |
| Subgraph naming |
Subgraph IDs with spaces need quotes |
subgraph "My Group" |
ArcKit Integration
This skill handles conversational Mermaid syntax questions — quick lookups, syntax examples, troubleshooting rendering issues, and learning about diagram types.
For formal architecture diagram generation with document control, project integration, C4 layout science, and governance compliance, use the $arckit-diagram command instead. It generates versioned diagram artifacts saved to your project directory with full traceability to requirements and architecture principles.
1---2name: mermaid-syntax3description: Mermaid syntax reference for writing or fixing a diagram in an artefact: flowchart, sequence, class, state, ER, Gantt, C4, mindmap, timeline and the other diagram types, node shapes, styling, theming, and why a diagram fails to render. Not needed for PlantUML (plantuml-syntax), or when the request is for a governed diagram artefact with document control, which $arckit-diagram produces.4---56# Mermaid Syntax Reference78A comprehensive reference for all 23 Mermaid diagram types plus configuration and theming. This skill provides official Mermaid syntax documentation sourced from the [mermaid-skill](https://github.com/WH-2099/mermaid-skill) project (auto-synced from upstream Mermaid docs).910**This skill ships reference material, not runnable scripts.** Read the relevant reference file with `Read`, apply the syntax, and write the diagram into the user's artefact. Do not `Bash`-execute anything from `references/` — they are Mermaid syntax docs, not commands.1112To look up syntax for a specific diagram type, identify the type from the table below and read the corresponding reference file.1314## Supported Diagram Types1516Select the appropriate diagram type and read the corresponding reference file:1718| Type | Reference | ArcKit Commands Using It |19| ---- | --------- | ------------------------ |20| Flowchart | [flowchart.md](references/flowchart.md) | `$arckit-diagram`, `$arckit-dfd`, `$arckit-roadmap`, `$arckit-plan`, `$arckit-backlog`, `$arckit-strategy`, `$arckit-story`, `$arckit-jsp-936` |21| Sequence Diagram | [sequenceDiagram.md](references/sequenceDiagram.md) | `$arckit-diagram` |22| Class Diagram | [classDiagram.md](references/classDiagram.md) | — |23| State Diagram | [stateDiagram.md](references/stateDiagram.md) | — |24| ER Diagram | [entityRelationshipDiagram.md](references/entityRelationshipDiagram.md) | `$arckit-data-model` |25| Gantt Chart | [gantt.md](references/gantt.md) | `$arckit-roadmap`, `$arckit-plan`, `$arckit-strategy`, `$arckit-story`, `$arckit-presentation` |26| Pie Chart | [pie.md](references/pie.md) | `$arckit-story`, `$arckit-presentation` |27| Mindmap | [mindmap.md](references/mindmap.md) | `$arckit-story` |28| Timeline | [timeline.md](references/timeline.md) | `$arckit-story` |29| Git Graph | [gitgraph.md](references/gitgraph.md) | — |30| Quadrant Chart | [quadrantChart.md](references/quadrantChart.md) | `$arckit-presentation` |31| Requirement Diagram | [requirementDiagram.md](references/requirementDiagram.md) | — |32| C4 Diagram | [c4.md](references/c4.md) | `$arckit-diagram`, `$arckit-presentation` |33| Sankey Diagram | [sankey.md](references/sankey.md) | — |34| XY Chart | [xyChart.md](references/xyChart.md) | — |35| Block Diagram | [block.md](references/block.md) | — |36| Packet Diagram | [packet.md](references/packet.md) | — |37| Kanban | [kanban.md](references/kanban.md) | — |38| Architecture Diagram | [architecture.md](references/architecture.md) | — |39| Radar Chart | [radar.md](references/radar.md) | — |40| Treemap | [treemap.md](references/treemap.md) | — |41| User Journey | [userJourney.md](references/userJourney.md) | — |42| ZenUML | [zenuml.md](references/zenuml.md) | — |4344## Configuration & Theming4546| Topic | Reference |47| ----- | --------- |48| Theming | [config-theming.md](references/config-theming.md) |49| Directives | [config-directives.md](references/config-directives.md) |50| Layouts | [config-layouts.md](references/config-layouts.md) |51| Configuration | [config-configuration.md](references/config-configuration.md) |52| Math | [config-math.md](references/config-math.md) |53| Tidy Tree | [config-tidy-tree.md](references/config-tidy-tree.md) |54| Examples | [examples.md](references/examples.md) |5556## C4 Layout Science5758For research-backed C4 diagram layout guidance (declaration ordering, edge crossing targets, colour standards, PlantUML directional hints), see [c4-layout-science.md](references/c4-layout-science.md). This ArcKit-specific reference supplements the upstream C4 syntax reference with graph drawing science and layout optimisation techniques.5960## Common Syntax Gotchas6162These are the most common Mermaid syntax errors encountered when generating diagrams:6364| Gotcha | Problem | Fix |65|--------|---------|-----|66| `<br/>` in flowchart edge labels | Mermaid flowchart parser rejects HTML in edge labels | Use comma-separated text: `-->\|"Uses, HTTPS"\|` |67| `end` as node ID | `end` is a reserved keyword in Mermaid | Use a different ID: `EndNode["End"]` |68| Gantt date formats | Gantt requires specific date format | Use `YYYY-MM-DD` (e.g., `2025-01-15`) |69| Gantt task status | Invalid task status keywords | Valid: `done`, `active`, `crit`, `milestone` |70| Parentheses in labels | Unescaped `()` breaks node parsing | Wrap in quotes: `Node["Label (with parens)"]` |71| Special chars in IDs | Hyphens, dots, spaces in node IDs | Use camelCase or underscores: `apiGateway`, `api_gateway` |72| ER combined keys | `FK UK` (space-separated) and `PK_FK` are parse errors, and the whole block silently fails to render | Comma-separate them: `uuid tenant_id FK, UK` |73| ER attribute comments | An unclosed `"`, or a `"` inside the comment, breaks the block | One pair of double quotes, last on the line, no `"` inside |74| ER cardinality tokens | Invented tokens (e.g. `\|\|--x{`) fail to parse | Left: `\|\|` `\|o` `}o` `}\|` — right: `\|\|` `o\|` `o{` `\|{` |75| Subgraph naming | Subgraph IDs with spaces need quotes | `subgraph "My Group"` |7677## ArcKit Integration7879This skill handles **conversational** Mermaid syntax questions — quick lookups, syntax examples, troubleshooting rendering issues, and learning about diagram types.8081For **formal architecture diagram generation** with document control, project integration, C4 layout science, and governance compliance, use the `$arckit-diagram` command instead. It generates versioned diagram artifacts saved to your project directory with full traceability to requirements and architecture principles.
tractorjuice