mermaid-syntax
Authoritative reference for Mermaid diagram syntax. Provides diagram types, syntax patterns, examples, and platform integration guidance for generating accurate Mermaid diagrams.
When & Why to Use This Skill
This Claude skill serves as an authoritative reference for Mermaid diagram syntax, enabling users to generate precise flowcharts, sequence diagrams, and system architectures. It provides comprehensive guidance on diagram types, syntax patterns, and platform integrations for Markdown-based environments like GitHub, Obsidian, and VS Code, ensuring high-quality visual documentation.
Use Cases
- System Architecture Design: Rapidly generate class diagrams and sequence diagrams to visualize software structures, inheritance, and API request/response flows.
- Workflow & Process Mapping: Create clear flowcharts and state diagrams to document business processes, user registration journeys, or complex logic transitions.
- Database Modeling: Design and communicate database schemas using Entity Relationship (ER) diagram syntax to define attributes and relationships.
- Project Planning: Visualize project timelines and schedules using Gantt charts and chronological timeline diagrams directly within technical documentation.
| name | mermaid-syntax |
|---|---|
| description | Authoritative reference for Mermaid diagram syntax. Provides diagram types, syntax patterns, examples, and platform integration guidance for generating accurate Mermaid diagrams. |
| allowed-tools | Read, Glob, Grep |
Mermaid Syntax Reference
Overview
Mermaid is a JavaScript-based diagramming tool that renders diagrams from Markdown-inspired text definitions. Diagrams render as SVG directly in browsers and are natively supported by GitHub, GitLab, Azure DevOps, Obsidian, and Notion.
Key advantages:
- Zero setup (browser-based rendering)
- Native Markdown integration (diagrams auto-sync with definitions)
- Simpler syntax than PlantUML
- No external dependencies
Limitations:
- Less customization than PlantUML
- C4 support is experimental
- No MindMap or JSON visualization
Diagram Types Quick Reference
| Type | Keyword | Best For |
|---|---|---|
| Flowchart | flowchart or graph |
Process flows, decision trees, workflows |
| Sequence | sequenceDiagram |
API calls, request/response flows |
| Class | classDiagram |
OOP structures, inheritance, relationships |
| State | stateDiagram-v2 |
State machines, lifecycle states |
| ER | erDiagram |
Database schemas, entity relationships |
| Gantt | gantt |
Project timelines, schedules |
| Pie | pie |
Distribution, proportions |
| Git Graph | gitGraph |
Branching strategies, commit history |
| C4 Context | C4Context |
System architecture (experimental) |
| Timeline | timeline |
Chronological events |
Markdown Integration
Mermaid diagrams are embedded in Markdown using fenced code blocks:
```mermaid
flowchart TD
A[Start] --> B[End]
```
Platform support:
- GitHub: Native rendering in README, issues, PRs, wikis
- GitLab: Native rendering in Markdown files
- Azure DevOps: Native rendering in wikis and repos
- Obsidian: Native with core plugin
- VS Code: With Markdown Preview Mermaid Support extension
Quick Reference Card
Flowchart
flowchart TD
A[Box] --> B{Decision}
B -->|Yes| C[Action]
B -->|No| D[Other]
Sequence
sequenceDiagram
A->>B: Request
B-->>A: Response
Class
classDiagram
class Name {
+attribute type
+method() return
}
A <|-- B : inherits
State
stateDiagram-v2
[*] --> State1
State1 --> State2 : event
State2 --> [*]
ER
erDiagram
ENTITY1 ||--o{ ENTITY2 : relationship
ENTITY1 {
type attribute PK
}
References
For detailed syntax and complete examples, see:
| Reference | Content | When to Load |
|---|---|---|
| flowchart.md | Node shapes, edge types, subgraphs | Creating flowcharts |
| sequence.md | Participants, arrows, activation, alt/loop | Creating sequence diagrams |
| class.md | Classes, visibility, relationships, cardinality | Creating class diagrams |
| state-er.md | State machines, ER diagrams, relationships | Creating state/ER diagrams |
| special-diagrams.md | Gantt, Git Graph, C4, styling, gotchas | Creating special diagrams |
Test Scenarios
Scenario 1: Creating a flowchart
Query: "Create a Mermaid flowchart for user registration process"
Expected: Skill activates, provides flowchart syntax with decision nodes and subgraphs
Scenario 2: Creating a sequence diagram
Query: "Generate a Mermaid sequence diagram for API authentication"
Expected: Skill activates, provides sequence syntax with participants and alt/loop blocks
Scenario 3: Creating an ER diagram
Query: "Create a Mermaid ER diagram for a blog database"
Expected: Skill activates, directs to state-er.md reference for entity attributes and relationships
Last Updated: 2025-12-28 Mermaid Version: 10.x / 11.x
Version History
- v1.1.0 (2025-12-28): Refactored to progressive disclosure - extracted content to references/
- v1.0.0 (2025-12-26): Initial release