---
title: mermaid-renderer
emoji: diagram
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "4.44.0"
app_file: app.py
pinned: false
license: mit
tags:
  - mermaid
  - diagram
  - visualization
  - code-generation
  - developer-tools
  - png
  - svg
  - pdf
  - cli
authors:
  - algorembrant
---

# mermaid-renderer

[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![Node.js](https://img.shields.io/badge/node.js-18%2B-green.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Mermaid CLI](https://img.shields.io/badge/@mermaid--js%2Fmermaid--cli-11%2B-purple.svg)](https://github.com/mermaid-js/mermaid-cli)
[![Formats](https://img.shields.io/badge/output-PNG%20%7C%20SVG%20%7C%20PDF-orange.svg)](#supported-formats)
[![Themes](https://img.shields.io/badge/themes-15%20built--in-teal.svg)](#built-in-themes)

Convert Mermaid diagrams to high-quality PNG, SVG, or PDF images from the command line. Supports all diagram types, 15 built-in themes from [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid), batch processing, parallel rendering, and file-watch mode.

---

## Features

- All Mermaid diagram types: flowcharts, sequence, state, class, ER, XY charts
- 15 curated themes (tokyo-night, catppuccin, dracula, nord, github, etc.)
- PNG, SVG, and PDF output
- Batch rendering with parallel workers
- Watch mode for live re-render on file change
- Custom background and foreground color overrides
- Scale factor control for high-DPI output
- Zero Python runtime dependencies beyond stdlib (Pillow optional)

---

## Requirements

| Requirement | Version | Notes |
|-------------|---------|-------|
| Python | 3.9+ | Standard library only |
| Node.js | 18+ | Required by mmdc |
| npm | 9+ | For installing mmdc |
| @mermaid-js/mermaid-cli | 11+ | The render engine |
| Chrome or Chromium | any | Headless browser for rendering |

---

## Installation

### 1. Install Node.js and npm

Download from https://nodejs.org/ or use your package manager:

```bash
# Ubuntu / Debian
sudo apt install nodejs npm

# macOS (Homebrew)
brew install node

# Windows (Chocolatey)
choco install nodejs
```

### 2. Install @mermaid-js/mermaid-cli

```bash
npm install -g @mermaid-js/mermaid-cli
```

Verify:
```bash
mmdc --version
```

### 3. Install Chrome or Chromium

**Option A — Puppeteer-managed (recommended, automatic):**

```bash
# After installing mermaid-cli, install its bundled Chrome:
node -e "const p = require('puppeteer'); p.executablePath();"
# Or use npx to install it:
npx puppeteer browsers install chrome
```

**Option B — System Chromium:**

```bash
# Ubuntu / Debian
sudo apt install chromium-browser

# macOS
brew install --cask google-chrome

# Windows: download from https://www.google.com/chrome/
```

### 4. Clone this repo and install Python deps

```bash
git clone https://github.com/algorembrant/mermaid-renderer.git
cd mermaid-renderer
pip install -r requirements.txt
```

### 5. Verify everything works

```bash
python render.py --check
```

Expected output:
```
mermaid-renderer — environment check
----------------------------------------
  Python      : 3.12.3
  mmdc        : /usr/local/bin/mmdc
  Chrome/Chrom: /home/user/.cache/puppeteer/chrome/.../chrome
  mmdc version: 11.12.0

  All dependencies OK. Rendering should work.
```

---

## Quick Start

### Render a file

```bash
python render.py diagram.mmd
# Output: diagram.png
```

### Inline diagram

```bash
python render.py --text "graph TD; A[Start] --> B{Decision}; B -->|Yes| C[Done]; B -->|No| D[End]"
# Output: diagram.png
```

### SVG output

```bash
python render.py diagram.mmd -o output.svg
```

### Apply a theme

```bash
python render.py diagram.mmd --theme tokyo-night
python render.py diagram.mmd --theme catppuccin-mocha -o dark.png
```

---

## Usage Reference

### Single File

| Command | Description |
|---------|-------------|
| `python render.py diagram.mmd` | Render to PNG (same name) |
| `python render.py diagram.mmd -o out.png` | Specify output path |
| `python render.py diagram.mmd -o out.svg` | SVG output |
| `python render.py diagram.mmd -o out.pdf` | PDF output |
| `python render.py --text "graph LR; A-->B"` | Inline diagram text |

### Themes

| Command | Description |
|---------|-------------|
| `python render.py d.mmd --theme tokyo-night` | Apply dark theme |
| `python render.py d.mmd --theme github-light` | Apply light theme |
| `python render.py d.mmd --bg "#1a1b26" --fg "#a9b1d6"` | Custom colors |
| `python render.py d.mmd --bg transparent` | Transparent background |
| `python render.py --list-themes` | Print all built-in themes |

### Quality / Size

| Command | Description |
|---------|-------------|
| `python render.py d.mmd --scale 2` | 2x resolution (default) |
| `python render.py d.mmd --scale 3` | 3x for print quality |
| `python render.py d.mmd --width 1920` | Set canvas width |

### Batch Mode

| Command | Description |
|---------|-------------|
| `python render.py --batch ./diagrams/` | Render all .mmd in directory |
| `python render.py --batch ./diagrams/ -o ./out/` | Output to separate directory |
| `python render.py --batch "./diagrams/*.mmd"` | Glob pattern |
| `python render.py --batch ./diagrams/ --workers 4` | Parallel (4 processes) |
| `python render.py --batch ./diagrams/ --format svg` | SVG batch output |

### Watch Mode

| Command | Description |
|---------|-------------|
| `python render.py diagram.mmd --watch` | Re-render on file change |
| `python render.py --batch ./diagrams/ --watch` | Watch entire directory |

### Utility

| Command | Description |
|---------|-------------|
| `python render.py --check` | Verify environment and deps |
| `python render.py --list-themes` | List all 15 built-in themes |
| `python render.py -v diagram.mmd` | Verbose (show mmdc output) |
| `python render.py --help` | Show help |

---

## Built-in Themes

| Theme | Type | Background | Accent |
|-------|------|------------|--------|
| `default` | light | `#FFFFFF` | (derived) |
| `zinc-light` | light | `#FFFFFF` | (derived) |
| `zinc-dark` | dark | `#18181B` | (derived) |
| `tokyo-night` | dark | `#1a1b26` | `#7aa2f7` |
| `tokyo-night-storm` | dark | `#24283b` | `#7aa2f7` |
| `tokyo-night-light` | light | `#d5d6db` | `#34548a` |
| `catppuccin-mocha` | dark | `#1e1e2e` | `#cba6f7` |
| `catppuccin-latte` | light | `#eff1f5` | `#8839ef` |
| `nord` | dark | `#2e3440` | `#88c0d0` |
| `nord-light` | light | `#eceff4` | `#5e81ac` |
| `dracula` | dark | `#282a36` | `#bd93f9` |
| `github-light` | light | `#ffffff` | `#0969da` |
| `github-dark` | dark | `#0d1117` | `#4493f8` |
| `solarized-light` | light | `#fdf6e3` | `#268bd2` |
| `solarized-dark` | dark | `#002b36` | `#268bd2` |
| `one-dark` | dark | `#282c34` | `#c678dd` |

---

## Supported Diagram Types

All Mermaid diagram types are supported:

- Flowcharts (`graph TD`, `graph LR`, etc.)
- Sequence diagrams (`sequenceDiagram`)
- State diagrams (`stateDiagram-v2`)
- Class diagrams (`classDiagram`)
- Entity-relationship diagrams (`erDiagram`)
- XY charts / bar / line (`xychart-beta`)
- Gantt charts (`gantt`)
- Pie charts (`pie`)
- Mindmaps (`mindmap`)
- Journey diagrams (`journey`)
- Git graphs (`gitGraph`)

---

## Supported Formats

| Format | Extension | Notes |
|--------|-----------|-------|
| PNG | `.png` | Raster, recommended for most uses. Use `--scale 2` or `--scale 3` for sharpness. |
| SVG | `.svg` | Vector, lossless, ideal for web and print. |
| PDF | `.pdf` | Vector PDF, fitted to diagram bounds. |

---

## Troubleshooting

### mmdc not found

```bash
npm install -g @mermaid-js/mermaid-cli
# Then ensure npm bin is on PATH:
export PATH="$(npm bin -g):$PATH"
```

### Chrome not found

```bash
# Install puppeteer-managed Chrome:
npx puppeteer browsers install chrome
# Or install system Chrome:
sudo apt install chromium-browser   # Linux
brew install --cask google-chrome   # macOS
```

### Sandbox errors on Linux

Add to your puppeteer config or run with:
```bash
# render.py auto-adds --no-sandbox when using puppeteer config
```

### Diagram renders blank / cut off

Increase canvas width:
```bash
python render.py diagram.mmd --width 2000
```

---

## Project Structure

```
mermaid-renderer/
  render.py           Main CLI script
  requirements.txt    Python dependencies (minimal)
  README.md           This file
  .gitignore          Git ignore rules
  .gitattributes      Git attributes
  examples/           Sample .mmd files
    flowchart.mmd
    sequence.mmd
    statediagram.mmd
    classdagram.mmd
    er.mmd
    xychart.mmd
```

---

## License

MIT License. See [LICENSE](LICENSE).

---

## Author

algorembrant

---

## Acknowledgments

- [mermaid-js/mermaid-cli](https://github.com/mermaid-js/mermaid-cli) — the render engine
- [lukilabs/beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) — theme system reference
- [mermaid.js.org](https://mermaid.js.org/) — Mermaid diagram specification