Exporting Mermaid Diagrams as SVG and PNG

Exporting Mermaid Diagrams

While Mermaid diagrams render beautifully in supported platforms, you often need static image files for presentations, emails, wikis that don't support Mermaid, or print documents. Mermaid supports export to SVG (vector) and PNG (raster).

SVG vs PNG

Aspect	SVG	PNG
Type	Vector	Raster
Scalability	Infinite — no quality loss	Fixed resolution
File size	Usually smaller	Larger at high resolution
Text	Selectable and searchable	Flattened into pixels
Best for	Docs, web, presentations	Chat, email, social media
Dark mode	Can be styled with CSS	Static — needs separate version

Browser-Based Export

The DevToolbox Mermaid viewer lets you export directly from the browser:

1. Write or paste your Mermaid code
2. Verify the rendered diagram
3. Click Export SVG or Export PNG
4. The file downloads automatically

This approach requires no installation and works on any operating system.

CLI-Based Export

For automated or batch exports, use the official Mermaid CLI:

# Install globally
npm install -g @mermaid-js/mermaid-cli

# Convert a single file
mmdc -i diagram.mmd -o diagram.svg
mmdc -i diagram.mmd -o diagram.png

# Specify dimensions for PNG
mmdc -i diagram.mmd -o diagram.png -w 1920 -H 1080

# Use a custom theme
mmdc -i diagram.mmd -o diagram.svg -t dark

# Batch convert all .mmd files
for f in *.mmd; do mmdc -i "$f" -o "${f%.mmd}.svg"; done

CI/CD Automation

Automate diagram generation in your pipeline:

# GitHub Actions example
- name: Generate diagrams
  uses: mermaid-js/mermaid-cli-action@v1
  with:
    input: docs/diagrams/
    output: docs/images/
    format: svg

This ensures diagrams are always up-to-date when documentation source files change.

Tips for High-Quality Exports

1. Use SVG for documentation — it scales perfectly and supports text search.
2. Set PNG background — by default, PNG exports may have a transparent background. Use --backgroundColor white if needed.
3. Increase PNG scale — use -s 2 for 2x resolution (retina displays).
4. Commit both source and output — keep .mmd files in version control alongside generated images for easy updates.