Mermaid to PNG, SVG & Image: Convert Guide (2026)

Writing diagrams as plain text instead of dragging boxes around a canvas is exactly why Mermaid.js caught on with engineers, documentation authors, and academics. The friction shows up later: the moment a diagram has to leave its rendering environment. A peer-reviewed journal, a conference deck, or a frozen PDF will not run your live markup. They want a flat image file.

This article maps out the reliable ways to turn Mermaid source into shareable images in 2026. We cover a one-click web editor, the maintained command-line tool, in-editor plugins for VS Code, the rendering baked into code hosts, a URL-based render service, and the natural-language route for people who would rather not touch syntax. By the end you should know exactly which path matches the task in front of you.

Quick Reference: Pick a Method Fast

If you only want the headline recommendation: reach for the Mermaid Live Editor when you need a single image right now, and the Mermaid CLI (mmdc) when the same job will repeat across many files. The table below covers the rest.

What Mermaid.js Does and Why Static Images Still Matter

Mermaid.js is an open-source JavaScript library that reads short text definitions and draws the corresponding diagram for you. The trade you make is conceptual rather than visual: you describe relationships in a compact markup syntax, and the renderer decides where every shape lands.

Here is the smallest useful example:

graph TD
    A[Collect water sample] --> B{pH below 7?}
    B -->|Yes| C[Flag as acidic]
    B -->|No| D[Flag as neutral or basic]
    C --> E[Log reading]
    D --> E

Six lines, and you get a tidy flowchart with no dragging or aligning. The same engine also covers sequence diagrams, Gantt charts, class and state diagrams, ER models, pie charts, and several more.

Diagram Types You Can Build

Where Live Rendering Falls Short

Inside any Markdown-aware surface, Mermaid looks great on its own. The trouble starts whenever the destination cannot execute the renderer:

• Academic writing: journal submission systems and LaTeX builds want a PNG or SVG figure, never a code fence
• Decks: neither PowerPoint nor Google Slides knows what to do with Mermaid markup
• PDF handoffs: the conversion step quietly discards anything Mermaid would have drawn
• Inboxes and chat: the person on the other end needs a picture, not a snippet to compile
• Anything printed: flyers, posters, and bound reports run on fixed-format images
• Archives: a saved image keeps displaying correctly even after Mermaid ships breaking syntax changes

A few lines of Mermaid can describe a full software architecture chart, but circulating that chart widely nearly always means exporting it as an image first

Method 1: Mermaid Live Editor (mermaid.live)

The Mermaid Live Editor is the official in-browser workspace for drafting, previewing, and downloading diagrams. Nothing to install, nothing to configure, which makes it the natural first stop.

Walkthrough

1. Visit mermaid.live
2. Type or paste your code into the left-hand pane
3. Watch the live preview update on the right as you edit
4. Open the Actions menu (or hit the download icon) up in the toolbar
5. Pick a format:
   • PNG: a raster file that drops cleanly into slides and word processors
   • SVG: a vector file that stays crisp at any size, ideal for publishing
6. Save it locally

Tuning the Output

A handful of controls let you shape the result before you hit download:

Where It Wins and Where It Falls Short

Use it when: you need one diagram converted in a hurry and do not want to set anything up.

Method 2: Mermaid CLI (mmdc)

When the same export has to happen again and again, automation beats clicking. The Mermaid CLI package (@mermaid-js/mermaid-cli) is the maintained command-line tool for that job, and it slots straight into build scripts.

Getting It Installed

A global install through npm gives you the mmdc command everywhere:

npm install -g @mermaid-js/mermaid-cli

Prefer not to install it permanently? Run it on the fly with npx:

npx @mermaid-js/mermaid-cli -i input.mmd -o output.svg

And if the box has no Node.js at all, the Docker image covers you:

docker run --rm -v "$PWD:/data" minlag/mermaid-cli -i /data/input.mmd -o /data/output.svg

A First Conversion

Drop your diagram into a .mmd file, say diagram.mmd:

graph TD
    A[Research Question] --> B[Literature Review]
    B --> C[Methodology Design]
    C --> D[Data Collection]
    D --> E[Analysis]
    E --> F[Publication]

From there, the output format is just a matter of the file extension and a flag or two:

# Convert to SVG
mmdc -i diagram.mmd -o diagram.svg

# Convert to PNG
mmdc -i diagram.mmd -o diagram.png

# Convert to PDF
mmdc -i diagram.mmd -o diagram.pdf

# Convert with a specific theme
mmdc -i diagram.mmd -o diagram.svg -t dark

# Convert with transparent background
mmdc -i diagram.mmd -o diagram.png -b transparent

# Convert with custom dimensions
mmdc -i diagram.mmd -o diagram.png -w 1920 -H 1080

Flags Worth Knowing

Converting a Whole Folder

A short shell loop turns every .mmd file in the directory into an SVG:

for file in *.mmd; do
    mmdc -i "$file" -o "${file%.mmd}.svg"
done

Where It Wins and Where It Falls Short

Use it when: you are a developer who wants repeatable exports wired into a build or docs pipeline.

Method 3: VS Code Extensions

If your day already lives in VS Code, you can preview and export Mermaid without ever opening another app. A few extensions handle this, each with a slightly different focus.

Markdown Preview Mermaid Support

This one teaches the standard VS Code Markdown preview how to draw Mermaid blocks.

Installation:

1. Open Extensions (Ctrl+Shift+X / Cmd+Shift+X)
2. Search for "Markdown Preview Mermaid Support"
3. Install the extension by Matt Bierner

Usage:

1. Drop your Mermaid code into a fenced block inside any Markdown file
2. Trigger the Markdown preview (Ctrl+Shift+V / Cmd+Shift+V)
3. The diagram appears inline in the preview pane
4. Right-click the rendered image to copy or save it

Mermaid Graphical Editor

This extension leans toward a more hands-on workflow: code and preview sit side by side, you get syntax highlighting and rendering that updates as you type, plus straight-to-file export for PNG and SVG.

Mermaid Export

Built for one purpose, which is pulling Mermaid blocks out of Markdown and writing them to image files.

How to use:

1. Author your diagram in a .md or .mmd file
2. Open the command palette (Ctrl+Shift+P / Cmd+Shift+P)
3. Run "Mermaid: Export"
4. Pick the format you want (SVG, PNG, or PDF)
5. Point it at a destination folder

How the Extensions Stack Up

Use it when: you and your team would rather keep diagram work inside the editor you already use.

Method 4: GitHub and GitLab Native Rendering

GitHub and GitLab both draw Mermaid diagrams on their own, directly inside Markdown files, issues, pull requests, and wikis. For display, there is nothing extra to set up.

GitHub

Native Mermaid support landed on GitHub back in February 2022, and the usage is simple:

1. Anywhere Markdown is accepted (a file, an issue, a PR comment), open a fenced block tagged with mermaid:

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

2. GitHub draws the diagram for you in both the preview and the published view.

Pulling an image out of GitHub:

• Right-click the rendered figure and pick "Save image as..." for a PNG
• For SVG, open browser dev tools, find the element, and lift the SVG markup
• For automation, query the rendered output through the GitHub API

GitLab

GitLab follows the identical fenced-block convention and renders Mermaid natively across README files, wikis, issue and merge-request descriptions, and comment threads.

What Native Rendering Cannot Do

Use it when: your team documents projects in GitHub or GitLab and wants diagrams sitting next to the code.

Method 5: AI-Powered Alternatives

Maybe you would rather not learn Mermaid syntax at all. AI tools let you state what you want in ordinary language and hand back a finished diagram, no markup involved.

Figviz Text to Diagram Generator

Figviz reads a plain-English description and builds a professional diagram from it. You explain the idea, and it does the drawing:

What comes back is a high-resolution figure you can grab as PNG or SVG.

Text to Diagram Generator

Transform text descriptions into professional diagrams instantly. No Mermaid syntax required: just describe what you need in plain language.

Try it free →

Figviz AI Flowchart Generator

When flowcharts specifically are the task, the AI Flowchart Generator takes natural-language input, lets you flip between layout directions, applies polished theming you can choose from, and exports to PNG or SVG in a single click.

AI Flowchart Generator

Generate professional flowcharts from text descriptions. Ideal for research workflows, process documentation, and decision trees.

Try it free →

Mermaid or AI? A Quick Decision Guide

Use it when: you are a researcher, student, or non-developer who wants strong-looking diagrams without spending time on Mermaid syntax.

Method 6: Mermaid Ink API

Mermaid Ink exposes a lightweight HTTP API that renders a diagram on its end and serves you back an image. The diagram travels inside the URL itself.

The Mechanics

1. Base64-encode the Mermaid source
2. Assemble a URL following the shape https://mermaid.ink/img/{base64code}
3. Drop that URL anywhere a normal image URL is accepted

Example

Take a trivial diagram:

graph TD
    A --> B

Encode that to base64, then plug the string into the path:

https://mermaid.ink/img/{base64-encoded-diagram}

Available Endpoints

Good Fits

• Email content: point at the URL instead of attaching a file
• README badges: diagrams that refresh as the underlying code shifts
• Wikis: surfaces that take image URLs but will not run JavaScript
• Docs sites: embed it with a plain image tag

Use it when: you can supply an image URL but the surface cannot execute JavaScript on its own.

Every Method at a Glance

This table lines up all six approaches so the right call is easy to spot:

Designing Mermaid Diagrams That Read Well

The export tool matters less than the diagram itself. These habits keep your output legible no matter how you render it.

1. One Idea per Diagram

Hold each figure to a single process or concept. Once a chart pushes past 15 to 20 nodes, you are almost always better off breaking it apart. Cram in too much and the whole thing turns to mush at normal image sizes.

2. Let the Flow Direction Follow the Reader

• Top-down (TD) fits hierarchies and tree-shaped structures
• Left-right (LR) fits sequences and timelines
• Whatever you pick, align it with the way your audience naturally scans

3. Label Nodes Like You Mean It

# Unclear
graph TD
    A --> B --> C

# Clear
graph TD
    A[Collect Data] --> B[Analyze Results]
    B --> C[Publish Findings]

4. Keep the Styling Uniform

Between the built-in themes and your own CSS, there is no excuse for diagrams that clash with one another. The four bundled themes are:

5. Match the Resolution to the Destination

• Slides: render at 1920x1080 or bigger
• Publications: lean on SVG, or PNG at 300 DPI and up
• Web: SVG when you can scale, or PNG at 2x for retina screens
• Print: PDF or SVG so nothing degrades when scaled

6. Confirm It in the Real Destination

Something that looks flawless in the Live Editor can shift once it lands in GitHub or VS Code. Open the exported file where it will actually live before you call it done.

For deeper guidance on figures meant for publication, see our guide to making scientific diagrams for research papers.

A diagram that is built with care carries a complicated process across to the reader, whether it started as Mermaid code or came from an AI generator

Fixing the Usual Snags

The Diagram Will Not Render

• Inspect the syntax: Mermaid cares about whitespace. Double-check indentation and make sure no rogue blank lines crept into your node definitions.
• Check the version: newer diagram types like gitGraph need a recent release. The current syntax lives at mermaid.js.org.
• Escape the tricky characters: symbols such as #, &, and < may need escaping depending on where they render.

The Export Looks Grainy

• Move to SVG so the output scales without loss
• Push the scale factor up with -s 2 or -s 3 on the CLI
• Pin the width and height to lock in exact dimensions
• Add -b transparent to drop the white box that otherwise frames the diagram inside dark documents

The CLI Will Not Install

• Make sure you are on Node.js 18 or newer
• Skip the global install and run through npx: npx @mermaid-js/mermaid-cli
• On Linux, Puppeteer sometimes wants extra Chromium libraries. The Puppeteer docs list what your distribution needs.
• No Node.js available? Lean on the Docker image: docker run --rm -v "$PWD:/data" minlag/mermaid-cli

The Fonts Come Out Wrong

Spell out the font inside a Mermaid config file:

{
  "theme": "default",
  "themeVariables": {
    "fontFamily": "Arial, sans-serif"
  }
}

Then feed that config to the CLI: mmdc -i input.mmd -o output.svg -c config.json

Frequently Asked Questions

Wrapping Up

Once you frame the decision around your actual situation, picking an export route is quick:

1. Need one image right now: the Mermaid Live Editor
2. Automating a recurring job: the Mermaid CLI (mmdc)
3. Working inside your editor: VS Code extensions
4. Documenting a repository: GitHub or GitLab native rendering
5. Skipping syntax entirely: AI tools like Figviz's Text to Diagram Generator
6. Embedding through a URL: the Mermaid Ink API

It comes down to how comfortable you are with tooling, how many diagrams are in play, and whether this is a one-time task or something you will repeat. Plenty of researchers and developers settle on a pairing: the Live Editor for fast single exports, the CLI for everything scripted.

Additional Resources

• Mermaid.js Official Documentation
• Mermaid CLI GitHub Repository
• How to Make Scientific Diagrams for Research Papers
• Text to Diagram Generator
• AI Flowchart Generator