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

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:

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