Mermaid Diagrams

Expert in generating diagrams from Markdown-inspired text definitions using Mermaid CLI.

When to Use This Skill

Use this skill when...	Use d2-diagrams instead when...
Embedding a diagram directly in a GitHub README or wiki	The output needs rich styling, custom themes, or icons
Authoring sequence diagrams or simple flowcharts	The diagram has deeply nested containers or complex layouts
Targeting platforms that natively render Mermaid (GitHub, GitLab, Notion)	Generating standalone SVG/PDF architecture diagrams
Diagrams must travel as plain text alongside the source	A premium layout engine (`tala`) materially improves the result

Core Expertise

Text-to-diagram: Convert simple text syntax to professional diagrams
Wide diagram support: Flowcharts, sequence, class, state, ERD, Gantt, pie, and more
Multiple outputs: SVG (default), PNG, PDF
Markdown integration: Embed in documentation, GitHub README, wikis

Installation

# npm (global)
npm install -g @mermaid-js/mermaid-cli

# npx (no install)
npx @mermaid-js/mermaid-cli -i input.mmd -o output.svg

Essential Commands

Basic Rendering

# Convert to SVG (default)
mmdc -i diagram.mmd -o diagram.svg

# Convert to PNG
mmdc -i diagram.mmd -o diagram.png

# Convert to PDF
mmdc -i diagram.mmd -o diagram.pdf

# Pipe from stdin
echo 'graph TD; A-->B' | mmdc --input - -o diagram.svg

Theming and Styling

# Use built-in theme
mmdc -i diagram.mmd -o diagram.svg -t dark
mmdc -i diagram.mmd -o diagram.svg -t forest
mmdc -i diagram.mmd -o diagram.svg -t neutral

# Custom CSS
mmdc -i diagram.mmd -o diagram.svg -C custom.css

# Background color
mmdc -i diagram.mmd -o diagram.png -b transparent
mmdc -i diagram.mmd -o diagram.png -b '#ffffff'

Image Settings

# Set dimensions (PNG)
mmdc -i diagram.mmd -o diagram.png -w 1920 -H 1080

# Scale factor
mmdc -i diagram.mmd -o diagram.png -s 2

Batch Rendering

# Render every .mmd in the directory to a sibling .svg
for f in *.mmd; do mmdc -i "$f" -o "${f%.mmd}.svg"; done

Diagram Types

Flowchart

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Direction options: TD (top-down), TB, BT, LR (left-right), RL

Sequence Diagram

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello
    B-->>A: Hi there
    A->>+B: Request
    B-->>-A: Response

Arrow types:

Arrow	Description
`->`	Solid line
`-->`	Dotted line
`->>`	Solid with arrowhead
`-->>`	Dotted with arrowhead
`-x`	Solid with cross
`-)`	Async (open arrow)

Class Diagram

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +fetch()
    }
    Animal <|-- Dog

Entity Relationship (ERD)

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

State Diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : submit
    Processing --> Complete : success
    Processing --> Error : failure
    Complete --> [*]
    Error --> Idle : retry

Gantt Chart

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Task A :a1, 2024-01-01, 30d
    Task B :after a1, 20d

Pie Chart

pie title Distribution
    "Category A" : 40
    "Category B" : 30
    "Category C" : 30

Git Graph

gitGraph
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit

Shape Syntax

Shape	Syntax
Rectangle	`[Text]`
Rounded	`(Text)`
Stadium	`([Text])`
Diamond	`{Text}`
Hexagon	`{{Text}}`
Circle	`((Text))`
Asymmetric	`>Text]`
Database	`[(Text)]`
Subroutine	`[[Text]]`

Styling

graph TD
    A[Styled]:::custom --> B
    classDef custom fill:#f96,stroke:#333,stroke-width:2px
    style A fill:#bbf,stroke:#f66

Docker Usage

# Using Docker
docker run --rm -v "$(pwd)":/data minlag/mermaid-cli -i /data/diagram.mmd -o /data/output.svg

# With UID for correct permissions
docker run -u $UID --rm -v "$(pwd)":/data minlag/mermaid-cli -i /data/diagram.mmd

Quick Reference

Flag	Description
`-i, --input`	Input file (use `-` for stdin)
`-o, --output`	Output file (determines format)
`-t, --theme`	Theme: default, dark, forest, neutral
`-b, --backgroundColor`	Background color
`-C, --cssFile`	Custom CSS file
`-c, --configFile`	Mermaid config JSON
`-w, --width`	Output width (PNG)
`-H, --height`	Output height (PNG)
`-s, --scale`	Scale factor
`-p, --puppeteerConfigFile`	Puppeteer config
`-h, --help`	Show help

Common Patterns

Architecture Diagram

graph TB
    subgraph Frontend
        A[React App]
    end
    subgraph Backend
        B[API Gateway]
        C[Service 1]
        D[Service 2]
    end
    subgraph Data
        E[(PostgreSQL)]
        F[(Redis)]
    end
    A --> B
    B --> C
    B --> D
    C --> E
    D --> F

API Flow

sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant S as Service
    participant D as Database

    C->>G: HTTP Request
    G->>S: Forward
    S->>D: Query
    D-->>S: Result
    S-->>G: Response
    G-->>C: HTTP Response

Troubleshooting

Linux Sandbox Issues

Create puppeteer-config.json:

{
  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
}

mmdc -p puppeteer-config.json -i diagram.mmd -o diagram.svg

Large Diagrams

# Increase timeout
mmdc -i large.mmd -o large.svg --timeout 60000

mermaid-diagrams