MermanDraw
Open Editor

How to Export Mermaid Diagrams to PNG and SVG

Which format to pick for docs, slides, email, and print, how to get a sharp high-resolution PNG, and three export routes: the browser editor, the mermaid CLI, and a build-time plugin.

5 min read

A Mermaid diagram renders where the Markdown is displayed. The moment it has to go somewhere else, a slide deck, a Google Doc, an email, a printed report, it needs to become an image. The choice is PNG or SVG, and the right one depends on where the image is going.

This post covers that choice, how to avoid the blurry-PNG problem, and three ways to produce the file: the browser editor, the mermaid command line tool, and build-time plugins for documentation sites.

PNG or SVG: pick by destination

SVG is vector. It scales to any size with no loss, the file is a few kilobytes, and text stays selectable. Use it for:

  • Web pages and static sites
  • PowerPoint, Keynote, and Word (all accept SVG directly)
  • Figma and other design tools
  • Print and PDF

PNG is pixels. It works everywhere an image works and needs no font or renderer on the receiving end. Use it for:

  • Google Docs and Google Slides, which do not accept SVG
  • Email, Slack, Teams, and Discord
  • Notion image blocks, Confluence pages, Jira tickets
  • Anywhere the SVG shows up as a broken image or a text dump
flowchart LR
    Code[Mermaid source] --> Render[Render in editor]
    Render --> Pick{Where is it going?}
    Pick -->|Slides or print| SVG[Export SVG]
    Pick -->|Docs, chat, email| PNG[Export PNG at 2x]
Mermaid diagram

Slides or print

Docs, chat, email

Mermaid source

Render in editor

Where is it going?

Export SVG

Export PNG at 2x

The decision, as a diagram. Try the export buttons on this one.
Try in editor →

Resolution: always export PNG at 2×

A 1× PNG is exactly as many pixels as the diagram occupies on a standard screen. On a retina laptop or a phone, the display has two or three physical pixels per CSS pixel, so the image is upscaled and the lines go soft. The same happens when you drop a 600-pixel-wide image into a slide and stretch it to fill.

Export at 2×. The file is four times the pixels, still small for a diagram, and it stays crisp on every screen you are likely to meet. MermanDraw exports PNG at 2× by default. The CLI takes a -s 2 flag. For print at 300 dpi, use 3× or switch to SVG.

Background and theme

Match the background to the destination. A dark-theme diagram pasted into a white document looks like a black rectangle; a white-background PNG on a dark slide looks like a sticker.

  • Light documents and slides: the Clean, Minimal, Paper, or Mono theme.
  • Dark slides and dark-mode docs: Dark or Neon.
  • Unknown or mixed: SVG, which carries no background on most themes, or a transparent PNG from the CLI.

In the editor, switch themes with the Theme button and the preview updates live. The export uses whatever is on screen, including the node and rank spacing you set in the Layout panel.

Route 1: the browser editor

The fastest path when you have one diagram to export.

  1. Paste the Mermaid code into the editor. Markdown fences are stripped on paste; a parse error highlights the line.
  2. Pick a theme. Adjust spacing in Layout if labels crowd each other.
  3. Click SVG or PNG in the toolbar. The file downloads immediately. PNG is 2× resolution.

If the destination is a chat tool or anywhere that unfurls links, the Share button is an alternative to an image: it creates a public page with the live diagram and a preview image, and anyone can open the code in the editor from there. The link lives as long as someone views it at least once every 180 days.

Route 2: the mermaid CLI

For many diagrams, or for diagrams in a repository that should regenerate on change, use @mermaid-js/mermaid-cli. It runs Mermaid in a headless Chromium (via Puppeteer), so the first run downloads a browser. After that it is a one-line command per file. 

# One-off: render a .mmd file to SVG
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

# PNG, 2x scale, white background
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png -s 2 -b white

# Transparent PNG with the dark theme
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png -s 2 -b transparent -t dark
Common invocations. Save the diagram source as a .mmd file first.

Useful flags: -s for scale, -b for background (a color name, hex, or transparent), -t for one of the built-in themes, -w for width in pixels, and -c config.json to pass a full Mermaid config including themeVariables. The output format follows the extension of the -o file: .svg, .png, or .pdf. 

# Render every .mmd under docs/ into docs/img/
for f in docs/*.mmd; do
  npx @mermaid-js/mermaid-cli -i "$f" -o "docs/img/$(basename "${f%.mmd}").svg"
done
Batch render in a shell loop, or wire the same command into a Makefile or npm script.

The CLI also reads Markdown: pass a .md file and it replaces each fenced mermaid block with an image reference, writing the images alongside. That is the quickest way to prepare a README for a host that does not render Mermaid, such as Bitbucket.

Route 3: build-time plugins for docs sites

If the diagrams live in a documentation site, let the build render them. Docusaurus has @docusaurus/theme-mermaid; MkDocs Material renders mermaid fences through pymdownx.superfences; Astro, VitePress, and Hugo have community plugins or render hooks. Two styles exist:

  • Client-side: the page ships the Mermaid script and renders in the reader's browser. Simple setup, diagrams follow the site's dark mode, but readers without JavaScript see code.
  • Build-time SVG: the build runs Mermaid once and inlines the SVG. Faster pages, no client script, works in RSS and print. Needs a headless browser in CI, like the CLI does.

Either way, the source stays as Mermaid in the Markdown and the images are never checked in by hand. See where Mermaid renders natively for the per-tool setup.

Checklist before you export

  • The diagram renders without errors. Fix parse errors first.
  • Direction suits the space: LR for wide slides, TD for tall pages.
  • Labels are readable at the size they will be shown. Shorten or add <br/> breaks.
  • Theme background matches the destination.
  • SVG for anything that accepts it; PNG at 2× for everything else.
  • The Mermaid source is saved somewhere the next editor can find it.

FAQ

Which is better for a Mermaid diagram, PNG or SVG?

SVG when the destination accepts it (web pages, PowerPoint, Keynote, Word, Figma, print). It scales without blur and the file is small. PNG when the destination does not (Google Docs, Google Slides, Slack, most email clients, Notion image blocks). Export PNG at 2× so it stays sharp on high-density screens.

Why does my exported PNG look blurry?

It was exported at 1× and then displayed on a 2× or 3× screen, or scaled up in the document. Export at 2× (the default in MermanDraw) and insert the image at or below its natural size. For print, 3× or SVG.

How do I export a Mermaid diagram with a transparent background?

SVG has no background unless the theme draws one, so it is transparent by default on most themes. For PNG, use the mermaid CLI with -b transparent. In the browser editor, pick a light theme for light documents or a dark theme for dark ones so the background matches.

Can I export Mermaid to PDF?

Export SVG, insert it into a document, and print that to PDF. The mermaid CLI can also write PDF directly with a .pdf output name. For a single diagram on a page, SVG inside a PDF gives the sharpest result.

Does the exported image include the code?

No. PNG and SVG are pictures. Keep the Mermaid source in the repository or next to the document, or create a share link from the editor so the diagram stays editable from the image caption.

Related