mermaid-renderer
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, 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:
# Ubuntu / Debian
sudo apt install nodejs npm
# macOS (Homebrew)
brew install node
# Windows (Chocolatey)
choco install nodejs
2. Install @mermaid-js/mermaid-cli
npm install -g @mermaid-js/mermaid-cli
Verify:
mmdc --version
3. Install Chrome or Chromium
Option A — Puppeteer-managed (recommended, automatic):
# 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:
# 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
git clone https://github.com/algorembrant/mermaid-renderer.git
cd mermaid-renderer
pip install -r requirements.txt
5. Verify everything works
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
python render.py --text "graph TD; A[Start] --> B{Decision}; B -->|Yes| C[Done]; B -->|No| D[End]"
# Output: diagram.png
SVG output
python render.py diagram.mmd -o output.svg
Apply a theme
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 |
Vector PDF, fitted to diagram bounds. |
Troubleshooting
mmdc not found
npm install -g @mermaid-js/mermaid-cli
# Then ensure npm bin is on PATH:
export PATH="$(npm bin -g):$PATH"
Chrome not found
# 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:
# render.py auto-adds --no-sandbox when using puppeteer config
Diagram renders blank / cut off
Increase canvas width:
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.
Author
algorembrant
Acknowledgments
- mermaid-js/mermaid-cli — the render engine
- lukilabs/beautiful-mermaid — theme system reference
- mermaid.js.org — Mermaid diagram specification
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support