mermaid

name	mermaid
description	Generate diagrams using Mermaid syntax. Use this skill when creating architecture diagrams, sequence diagrams, ER diagrams, flowcharts, or any visual documentation in markdown files.

Generate Mermaid diagrams by writing code blocks with the `mermaid` language identifier in markdown files. Mermaid syntax is rendered natively by GitHub, GitLab, and most markdown editors. Choose the appropriate diagram type (flowchart, sequence, ER, class, or state) based on what you need to visualize. Mermaid code blocks that render as diagrams. Example output format:

flowchart TD
    A[Start] --> B[Process]
    B --> C[End]

The diagram renders visually in GitHub, GitLab, and compatible markdown viewers.

Mermaid Diagram Skill

When to Use This Skill

• Documenting system architecture or component relationships
• Visualizing API request/response flows
• Creating database schema diagrams from models
• Illustrating state machines or workflows
• Adding visual documentation to markdown files

Overview

Mermaid is a JavaScript-based diagramming tool that renders markdown-like syntax into diagrams. GitHub, GitLab, and many markdown editors render Mermaid blocks natively.

No installation required for GitHub rendering - just use fenced code blocks with mermaid language identifier.

Prerequisites

Option 1: GitHub/GitLab (Recommended)

No setup needed. Wrap diagrams in triple backticks with mermaid language:

```mermaid
flowchart LR
    A --> B
```

Option 2: Mermaid CLI (Local Rendering)

npm install -g @mermaid-js/mermaid-cli
mmdc -i input.mmd -o output.svg

Option 3: VS Code Extension

Install "Markdown Preview Mermaid Support" extension for live preview.

Flowchart Diagrams

Use for architecture, decision trees, and process flows.

Basic Syntax

flowchart TD
    A[Rectangle] --> B(Rounded)
    B --> C{Diamond}
    C -->|Yes| D[Result 1]
    C -->|No| E[Result 2]

Direction Options

• TD or TB - Top to bottom
• LR - Left to right
• BT - Bottom to top
• RL - Right to left

Architecture Example

flowchart TD
    subgraph Client
        UI[React App]
    end
    subgraph Server
        API[Express API]
        Auth[Auth Service]
    end
    subgraph Data
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    UI -->|HTTP| API
    API --> Auth
    API --> DB
    API --> Cache

Sequence Diagrams

Use for API flows, authentication sequences, and message passing.

Basic Syntax

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database

    C->>S: POST /api/users
    S->>DB: INSERT user
    DB-->>S: OK
    S-->>C: 201 Created

Arrow Types

• ->> Solid line with arrowhead
• -->> Dotted line with arrowhead
• -x Solid line with X (async)
• --x Dotted line with X

With Loops and Conditionals

sequenceDiagram
    participant U as User
    participant A as API
    participant Auth as Auth Service

    U->>A: Login request
    A->>Auth: Validate credentials

    alt Valid credentials
        Auth-->>A: Token
        A-->>U: 200 OK + Token
    else Invalid
        Auth-->>A: Error
        A-->>U: 401 Unauthorized
    end

    loop Every 15 minutes
        U->>A: Refresh token
        A-->>U: New token
    end

ER Diagrams

Use for database schemas and entity relationships.

Basic Syntax

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"

Cardinality Notation

• || - Exactly one
• o| - Zero or one
• }| - One or more
• }o - Zero or more

With Attributes

erDiagram
    USER {
        int id PK
        string email UK
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    USER ||--o{ ORDER : places

Class Diagrams

Use for object models and component relationships.

Basic Syntax

classDiagram
    class User {
        +int id
        +string email
        +login()
        +logout()
    }
    class Order {
        +int id
        +decimal total
        +submit()
    }
    User "1" --> "*" Order : places

Relationship Types

• <|-- Inheritance
• *-- Composition
• o-- Aggregation
• --> Association
• ..> Dependency

State Diagrams

Use for state machines and workflow states.

Basic Syntax

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Approved : approve
    Review --> Draft : reject
    Approved --> Published : publish
    Published --> [*]

With Nested States

stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Idle
        Idle --> Processing : start
        Processing --> Idle : complete
    }

    Active --> Suspended : suspend
    Suspended --> Active : resume
    Active --> [*] : terminate

Best Practices

1. Keep diagrams focused - One concept per diagram, split complex systems into multiple diagrams
2. Use meaningful labels - API not A, Database not DB (unless space-constrained)
3. Add subgraphs for grouping related components in flowcharts
4. Use aliases in sequence diagrams (participant C as Client) for readability
5. Include cardinality in ER diagrams - relationships are ambiguous without it
6. Test rendering on GitHub before committing - some syntax varies between versions
7. Link to details - Diagrams show structure; link to docs for implementation details

Reference Documentation

• Official Docs: https://mermaid.js.org/
• Live Editor: https://mermaid.live/
• GitHub Support: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
• Syntax Reference: https://mermaid.js.org/syntax/flowchart.html