Mermaid to PNG: Every Route, and Which One You Actually Want
Short answer: paste the diagram into the Mermaid Live Editor and click download for a one-off, run `mmdc -i diagram.mmd -o diagram.png -s 3` when you need it repeatable, and export SVG instead of PNG whenever the destination will accept it. The interesting question is not how to produce the file. It is what you lose the moment the diagram stops being text.
What are the actual ways to convert Mermaid to PNG?
There are four, and they are not interchangeable.
The live editor. Paste your definition at mermaid.live, preview it, download PNG or SVG. Zero setup. Nothing is recorded, which means the next person who needs the same image repeats the whole process by hand.
The command-line renderer. `@mermaid-js/mermaid-cli` gives you `mmdc`, which takes a `.mmd` file and writes a `.png`, `.svg`, or `.pdf`. It runs headless Chromium underneath, so the output matches what the browser would draw. Because it is a command, it belongs in a Makefile, a pre-commit hook, or a CI job.
``` npm install -g @mermaid-js/mermaid-cli mmdc -i architecture.mmd -o architecture.png -s 3 -b transparent ```
The `-s` flag is the one that matters. It is a scale multiplier, and it is the difference between a diagram that reads on a projector and one that does not.
A script you own. Load `mermaid.js` in a headless browser, render the definition, screenshot the SVG element. This is what every tool above does internally. You write it yourself when you need something the CLI will not give you: a specific font, a per-diagram theme, a batch over a documentation tree, or a naming convention tied to your repository layout.
The online converters. A large ring of sites — `mermaideditor.io`, `mermaid2img.com`, `imagetomermaid.com`, `mermaidonline.live` and others — wrap the same render step in a web form and compete on export scale, offering 2x, 4x, sometimes 8x. Convenient, and fine for a one-off. You are pasting your diagram into someone else's server, which is a consideration when the diagram is your internal architecture.
Which route should I use?
| Route | Setup | Repeatable | Resolution control | Best for | |---|---|---|---|---| | Live editor | None | No | Fixed | A single image, right now | | `mmdc` CLI | npm install | Yes | `-s` scale flag | Docs builds, CI, anything regenerated | | Custom script | Real work | Yes | Total | Batch jobs, custom fonts or themes | | Online converter | None | No | Site-dependent, often 2x–8x | A one-off when you cannot install anything |
The decision rule is short. Will this image ever need to be regenerated? If yes, use the CLI and commit the command, not just the output. If no, use the live editor and move on.
Why is my exported Mermaid PNG blurry?
Because PNG is a raster format and you exported it at screen scale.
A PNG stores a fixed grid of pixels. Export a diagram at 1x and it holds roughly 96 dots per inch, which is exactly enough for the browser window you were looking at and nothing else. Project it, print it, or let someone zoom in on a slide, and the renderer has no additional detail to draw with, so it interpolates. That is the blur.
The fix is to render larger at export time rather than scaling up afterwards. With the CLI, `-s 3` or `-s 4` produces an image with three or four times the linear detail. With the online converters, pick their 4x option rather than the default. Scaling a finished 1x PNG in PowerPoint does not recover anything, because the detail was never captured.
The better fix, where the destination allows it, is to skip the raster format altogether.
Should I export SVG instead of PNG?
Usually yes.
SVG stores the diagram as shapes and text rather than pixels, so it stays sharp at any size and the text inside it remains real text — selectable, searchable, and re-colourable. For documentation sites, blogs, and anything that will be viewed at more than one size, SVG is the correct default.
PNG earns its place in exactly one situation: the destination will not accept SVG. That covers a surprising number of places, including some chat clients, some wikis, and several email clients. PowerPoint and Google Slides both accept SVG now, which removes the most common historical reason people reached for PNG.
So the order of preference is SVG first, PNG at 3x or 4x when SVG is refused, and never a 1x PNG.
What does a PNG export cost you?
This is the part the converter pages do not discuss, and it matters more than resolution.
A Mermaid definition is text. It lives next to the code, it diffs in a pull request, and it is reviewed like anything else. The moment you export it, you have created a second artifact that looks identical and is not connected to the first. The definition changes; the PNG does not. Nobody notices, because a stale diagram looks exactly as authoritative as a current one.
Two practices contain this. Either generate the image during the build, so it cannot drift, or do not commit the image at all and let the platform render the definition. On GitHub, the second option is free: a fenced block tagged `mermaid` renders natively, which is the subject of our guide to putting Mermaid diagrams in a GitHub README.
There is also a second cost, which only shows up in a meeting.
What happens when a PNG diagram reaches a slide?
It stops explaining anything.
A static image of a twelve-node flowchart hits the audience all at once. They scan it, look for the thing you are talking about, fail to find it, and stop listening while they search. The diagram that was perfectly clear in the repository — where the reader sets their own pace — becomes a wall the second it is projected and the pace is yours.
The information the diagram encodes is sequential. Step one leads to step two. A request enters here and leaves there. A static export throws that sequence away and asks the viewer to reconstruct it from arrow directions, in real time, while you talk over them.
This is the gap between a diagram that documents and a diagram that presents, and it is the same gap described in why static diagrams fail in presentations. Exporting at 8x does not close it. Higher resolution makes an unreadable slide unreadable in more detail.
The alternative is to keep the motion the diagram implies. FluxDiagram takes a Mermaid definition — flowchart, sequence, class, Gantt, or pie — and produces an animated version that reveals the structure in order, exported as GIF, MP4, or WebM, which you then embed into PowerPoint, Google Slides, or Keynote like any other media file. The definition stays the source; the animation is the presentation view of it. That approach is covered in more depth in converting a Mermaid diagram into an animation.
Frequently asked questions
Can I convert Mermaid to PNG without installing anything? Yes. The Mermaid Live Editor renders in your browser and downloads the result directly, and the online converters do the same with more scale options. Neither requires an install. Both are manual, so neither is a good fit for an image that will be regenerated.
How do I get a transparent background? Pass `-b transparent` to `mmdc`. Most online converters expose the same choice as a toggle between white and transparent. Transparent is the right default for anything going onto a coloured slide.
Does a PNG export keep the diagram searchable? No. PNG flattens text into pixels, so nothing in the image is selectable or indexable. SVG keeps text as text. If the diagram has to be searchable inside a document, that alone decides the format.
FluxDiagram generates animated diagrams you embed into the deck you already have, in PowerPoint, Google Slides or Keynote. Paste a Mermaid definition into the Mermaid converter to see the animated version of a diagram you have already written.