Mermaid Syntax Reference Skill

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

Agent Skills: Mermaid Syntax Reference

Install this agent skill to your local

Skill Files