mermaid-diagrams

Mermaid Diagrams

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

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