mermaid-syntax

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