Mermaid Syntax
Documentsmermaid-syntaxMermaid Syntax is an Agent Skill for documents published in the tractorjuice/arc-kit repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
This skill should be used when the user asks about Mermaid diagram syntax, how to write flowchart, sequence, class, state, ER, Gantt, C4, mindmap, timeline, or other diagram types, node shapes, styling, theming, or rendering errors.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/tractorjuice/arc-kit/blob/HEAD/plugins/arckit-claude/skills/mermaid-syntax/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mermaid-syntax, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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 |
| Missing semicolons in ER | ER diagram attributes need specific syntax | Follow entity { type name } pattern |
| 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.