Export Mermaid to PNG, SVG, and PDF: rendering formats explained

A diagram in your editor is great. A diagram embedded in a README, presentation, or report is how it reaches your team. Mermaid exports to PNG (raster), SVG (vector), and PDF — each with tradeoffs in size, quality, and editability. Knowing when to use each one saves time and prevents blurry diagrams at 4x zoom.

Format comparison at a glance

Format	Type	File Size	Quality at Scale	Editability	Best for
PNG	Raster	Small	Degrades if enlarged	No	Web, Slack, quick previews
SVG	Vector	Medium	Sharp at any size	Yes (with code editor)	Docs, interactive dashboards, web
PDF	Vector	Medium	Sharp at any size	Limited (print-optimized)	Reports, slides, printing

PNG: the quick share

PNG is a raster format — pixels in a grid. Mermaid renders your diagram at a fixed resolution (usually 1200×800 by default) and saves it as a PNG file. It's small, compresses well, and displays instantly everywhere.

Pros:

• Smallest file size
• Works in every tool (Slack, email, presentations)
• Fast to generate
• No dependencies needed

Cons:

• Blurry if enlarged beyond 2x
• No interactivity
• Baked-in colors; can't change the theme later

When to use PNG:

• Social media posts (Twitter, LinkedIn)
• Slack messages and quick feedback
• Low-resolution previews
• Embedded in web pages as static images

Example from MermaidCreator: Go to the playground, draw a diagram, and click "Download as PNG". The browser generates a PNG and downloads it in seconds.

SVG: the portable vector

SVG (Scalable Vector Graphics) is vector format — shapes and curves defined mathematically. A diagram that's 300 bytes of SVG code stays sharp whether you view it at 100×100 or 4000×4000 pixels.

Pros:

• Infinitely scalable without loss
• Medium file size (usually smaller than PDF)
• Editable as text (XML-based)
• Can be styled with CSS or embedded in HTML
• Works in modern browsers, design tools (Figma, Illustrator)

Cons:

• Slightly larger than PNG for simple diagrams
• Not optimal for printing (may need font embedding)
• Some tools don't handle complex SVGs well

When to use SVG:

• GitHub READMEs (GitHub renders SVG inline)
• Technical documentation sites
• Design systems and style guides
• Responsive web pages (scale to any screen size)
• Version control (SVG is text, diffs are readable)

Embedding SVG in Markdown:

![System Architecture](architecture.svg)

GitHub and most markdown renderers display SVGs natively. You can also embed SVG directly in HTML:

<iframe src="diagram.svg"></iframe>

Editing an SVG: SVG is XML. You can open it in a text editor and tweak colors, labels, or coordinates by hand. Or edit in MermaidCreator, re-export, and replace the old SVG.

PDF: the print format

PDF is a vector format optimized for printing and archival. Every font, color, and page break is fixed — what you see on screen is what prints.

Pros:

• Perfect for printing and PDFs
• Portable across devices and operating systems
• Embed fonts so diagrams look the same everywhere
• Great for reports, slide decks, and formal docs

Cons:

• Largest file size of the three
• Not editable without specialized tools
• Overkill for web-only sharing
• Less flexible for responsive layouts

When to use PDF:

• Printed reports and whitepapers
• PowerPoint or Keynote slide decks (export to PDF, then insert)
• Archival (diagrams for historical records)
• Client deliverables and formal documentation

Workflow: from diagram to deliverable

For a README or docs site

1. Create your diagram in MermaidCreator
2. Export as SVG
3. Commit to your repository
4. Link in Markdown: ![alt text](path/to/diagram.svg)

GitHub and most static site generators render SVG automatically, and the diagram stays version-controlled and reviewable in pull requests.

For a presentation

1. Create your diagram in MermaidCreator
2. Export as PNG (for quick Slack reviews) or SVG (for print-quality slides)
3. Insert into PowerPoint/Keynote
4. Optional: right-click → "Edit with Mermaid" if using cloud tools that support it

For a printed report

1. Create your diagram in MermaidCreator
2. Export as PDF
3. Insert into your report document (Word, LaTeX, InDesign)
4. No resizing needed — the PDF scales perfectly to any page size

For a blog or web app

1. Create your diagram in MermaidCreator
2. Embed live using our code blocks (best for dynamic content):

<script src="https://cdn.jsdelivr.net/npm/mermaid@latest/dist/mermaid.min.js"></script>
<div class="mermaid">
  flowchart LR
    A[Start] --> B{Decision} --> C[End]
</div>

3. Or export as PNG for a static image
4. Or export as SVG for vector scalability

Automating exports

For large teams or CI/CD pipelines, export diagrams programmatically:

Node.js + mermaid CLI

npm install -g @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.png
mmdc -i diagram.mmd -o diagram.svg
mmdc -i diagram.mmd -o diagram.pdf

Python + mermaid.ink

import requests

mermaid_code = """
flowchart LR
    A[Start] --> B[End]
"""

# PNG
response = requests.get(f"https://mermaid.ink/img/{mermaid_code}")
with open("diagram.png", "wb") as f:
    f.write(response.content)

# SVG
response = requests.get(f"https://mermaid.ink/svg/{mermaid_code}")
with open("diagram.svg", "w") as f:
    f.write(response.text)

Mermaid.ink is a free rendering service — paste your diagram code and get back an image URL. Great for CI/CD pipelines that generate diagrams on the fly.

GitHub Actions

Auto-generate diagrams from your repository:

- name: Render Mermaid
  uses: mermaid-js/mermaid-cli@v10
  with:
    files: docs/*.mmd
    output: docs/images/

Commit the source .mmd file; CI generates the images and commits them too.

Quality and rendering tips

Resolution matters:

• PNG: default 1200×800. For larger diagrams, request higher resolution in your export tool.
• SVG/PDF: resolution-independent, but fonts and line weights matter. Test at print size.

Colors and contrast:

• Dark backgrounds in your editor? Export might look different. Preview before sharing.
• SVG: inherit color from CSS if embedded in a webpage.
• PDF: embed fonts to ensure consistency across devices.

Size optimization:

• PNG: compress with tools like TinyPNG (90% of file size, no visible loss).
• SVG: minify with svgo (npm install -g svgo && svgo diagram.svg).
• PDF: depends on content; usually fine as-is.

Comparison table: which export to use?

graph TD
    A{Where is the diagram going?}
    
    A -->|Web page, GitHub, docs| B[Use SVG]
    A -->|Slack, email, social| C[Use PNG]
    A -->|Printed report, slide deck| D[Use PDF]
    
    B --> B1["✓ Scalable<br/>✓ Version-control friendly<br/>✓ Editable"]
    C --> C1["✓ Small files<br/>✓ Universal<br/>✓ Fast"]
    D --> D1["✓ Print-perfect<br/>✓ Portable<br/>✓ Archival"]

FAQ

Why is my PNG blurry when enlarged? PNG is raster. It's fixed resolution. If you're zooming in, you'll see pixelation. Use SVG for any format where you might scale the diagram.

Can I edit an SVG diagram later? Yes — open it in a text editor or re-import it into MermaidCreator. Mermaid detects the syntax and lets you edit it visually.

What if I need a high-res PNG for printing? When exporting, specify a higher output resolution (usually 2-4x default). Your export tool should have a "resolution" or "scale" option. Or export as PDF instead — it prints perfectly at any size.

Should I commit SVG files to git? Yes. SVG is text-based, so diffs show exactly what changed (a label, a color, a connection). Much better than committing binary PNG files.

Can I make my SVG interactive? Yes. SVG is HTML-compatible. Add click handlers, hover effects, or embed it in a React component. For interactive dashboards, consider tools like Observable or D3.js that wrap Mermaid.

Export formats depend on your use case — pick the right one and you'll save time and frustration. Use MermaidCreator to sketch, export what fits your workflow, and move on.