laurigates/mermaid-diagrams

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

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

Agentic Optimizations

| Context | Command | |---------|---------| | Quick SVG | mmdc -i diagram.mmd -o diagram.svg | | PNG with transparency | mmdc -i diagram.mmd -o diagram.png -b transparent | | High-res PNG | mmdc -i diagram.mmd -o diagram.png -s 2 | | Dark theme | mmdc -i diagram.mmd -o diagram.svg -t dark | | Batch process | for f in *.mmd; do mmdc -i "$f" -o "${f%.mmd}.svg"; done | | Stdin pipe | echo 'graph TD; A-->B' \| mmdc --input - -o out.svg |

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