How to Convert Mermaid Diagrams to Images: Complete Guide (2026)

Mermaid.js has become one of the most popular ways for developers, researchers, and technical writers to create diagrams using simple text-based syntax. But when it comes time to embed those diagrams in a research paper, presentation, or document that does not support Mermaid rendering, you need to convert them to standard image formats like PNG, SVG, or PDF.

This guide covers every reliable method for converting Mermaid diagrams to images in 2026--from browser-based tools and the official CLI to VS Code extensions, native platform rendering, and AI-powered alternatives. By the end, you will know exactly which method fits your workflow.

What Is Mermaid.js and Why Convert Diagrams to Images?

Mermaid.js is an open-source JavaScript library that generates diagrams and charts from text-based definitions. Instead of dragging shapes around a canvas, you write a simple markup language and Mermaid renders the visual output.

Here is a basic example:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

This code produces a clean flowchart without any manual drawing. Mermaid supports flowcharts, sequence diagrams, Gantt charts, class diagrams, state diagrams, ER diagrams, pie charts, and more.

Supported Diagram Types

Why You Need Image Exports

While Mermaid renders beautifully in Markdown-compatible platforms, many situations require static image files:

• Research papers and theses -- journals and LaTeX documents need PNG or SVG figures
• Presentations -- PowerPoint and Google Slides cannot render Mermaid natively
• Documentation PDFs -- exported docs lose Mermaid rendering
• Email and messaging -- diagrams shared via email need to be images
• Print materials -- posters, handouts, and reports require image formats
• Archival purposes -- images remain readable regardless of Mermaid version changes

Mermaid excels at creating diagrams like software architecture charts from simple text definitions--but sharing them often requires image export

Method 1: Mermaid Live Editor (mermaid.live)

The Mermaid Live Editor is the official web-based tool for writing, previewing, and exporting Mermaid diagrams. It is the fastest way to get started.

Step-by-Step Instructions

1. Open mermaid.live in your browser
2. Write or paste your Mermaid code in the left panel
3. Preview the rendered diagram in the right panel in real time
4. Click the Actions menu (or the download icon) in the toolbar
5. Select your export format:
   • PNG -- raster image, best for presentations and documents
   • SVG -- vector image, best for publications and scaling
6. Download the file to your computer

Configuration Options

The Live Editor allows you to customize the output before exporting:

Pros and Cons

Best for: Quick, one-off exports when you need a single diagram converted to an image.

Method 2: Mermaid CLI (mmdc)

The Mermaid CLI (@mermaid-js/mermaid-cli) is the official command-line tool for converting Mermaid files to images. It is the best option for automation, batch processing, and CI/CD pipelines.

Installation

Install the CLI globally using npm:

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

Or use it without installing via npx:

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

You can also run it via Docker:

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

Basic Usage

Create a Mermaid definition file (e.g., diagram.mmd):

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

Convert to different formats:

# 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

Advanced Options

Batch Processing

Convert all .mmd files in a directory:

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

Pros and Cons

Best for: Developers who need automated, repeatable exports in build pipelines or documentation workflows.

Method 3: VS Code Extensions

If VS Code is your primary editor, several extensions provide Mermaid preview and export functionality without leaving the IDE.

Markdown Preview Mermaid Support

This extension adds Mermaid diagram rendering to the built-in Markdown preview in VS Code.

Installation:

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

Usage:

1. Write Mermaid code inside a fenced code block in any Markdown file
2. Open the Markdown preview (Ctrl+Shift+V / Cmd+Shift+V)
3. The Mermaid diagram renders inline
4. Right-click the preview to save or copy the rendered output

Mermaid Graphical Editor

For a more visual approach, the Mermaid Graphical Editor extension provides:

• Side-by-side code and visual preview
• Direct export to PNG and SVG
• Syntax highlighting for Mermaid code
• Real-time rendering as you type

Mermaid Export

The Mermaid Export extension is specifically designed for converting Mermaid diagrams embedded in Markdown files to image files.

How to use:

1. Write your Mermaid diagram in a .md or .mmd file
2. Open the command palette (Ctrl+Shift+P / Cmd+Shift+P)
3. Search for "Mermaid: Export"
4. Select your output format (SVG, PNG, PDF)
5. Choose the destination folder

Comparison of VS Code Extensions

Best for: Developers and technical writers who work primarily in VS Code and want integrated diagram workflows.

Method 4: GitHub and GitLab Native Rendering

Both GitHub and GitLab render Mermaid diagrams natively in Markdown files, issues, pull requests, and wikis. This means your diagrams appear as rendered visuals without any extra tools.

GitHub

GitHub has supported Mermaid rendering since February 2022. To use it:

1. In any Markdown file, issue, or PR comment, create a fenced code block with the mermaid language identifier:

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

2. GitHub automatically renders the diagram in the preview and published view.

Exporting from GitHub:

• Right-click the rendered diagram and select "Save image as..." to download as PNG
• For SVG, inspect the element and copy the SVG markup
• Use the GitHub API to programmatically access rendered diagrams

GitLab

GitLab also supports native Mermaid rendering using the same fenced code block syntax. GitLab renders Mermaid in:

• README files and wikis
• Issue and merge request descriptions
• Comments and notes

Limitations of Native Rendering

Best for: Teams already using GitHub or GitLab who need diagrams in their documentation and README files.

Method 5: AI-Powered Alternatives

If you want to create diagrams without learning Mermaid syntax at all, AI-powered tools let you describe what you need in plain language and generate professional diagrams automatically.

ConceptViz Text to Diagram Generator

ConceptViz transforms natural language descriptions into professional diagrams. Instead of writing Mermaid code, you describe your diagram in plain English:

The AI generates a polished diagram that you can download in high-resolution PNG or SVG format.

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 →

ConceptViz AI Flowchart Generator

For flowcharts specifically, the AI Flowchart Generator provides:

• Natural language input
• Multiple layout options (top-down, left-right)
• Professional styling with customizable themes
• One-click export to PNG and SVG

AI Flowchart Generator

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

Try it free →

When to Choose AI Over Mermaid

Best for: Researchers, students, and non-developers who need professional diagrams without learning Mermaid syntax.

Method 6: Mermaid Ink API

Mermaid Ink provides a simple HTTP API for rendering Mermaid diagrams as images. You encode your Mermaid code in a URL and receive a rendered image.

How It Works

1. Base64-encode your Mermaid diagram code
2. Construct a URL in the format: https://mermaid.ink/img/{base64code}
3. Use the URL directly in any context that supports image URLs

Example

For a simple diagram:

graph TD
    A --> B

Encode it to base64 and use:

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

API Endpoints

Use Cases

• Embedding in emails -- use the image URL directly
• README badges -- dynamic diagrams that update when code changes
• Wiki pages -- platforms that support image URLs but not Mermaid
• Documentation sites -- embed via standard image tags

Best for: Embedding rendered Mermaid diagrams in contexts where you can use image URLs but cannot run JavaScript.

Comparison of All Methods

Here is a side-by-side comparison of every Mermaid-to-image conversion method covered in this guide:

Best Practices for Mermaid Diagram Design

Regardless of which conversion method you choose, following these design practices will produce better-looking diagrams.

1. Keep Diagrams Focused

Limit each diagram to a single concept or process. If your diagram has more than 15-20 nodes, split it into multiple diagrams. Complex diagrams with too many elements become unreadable at standard image resolutions.

2. Choose the Right Direction

• Top-down (TD) works best for hierarchical processes and workflows
• Left-right (LR) works best for sequential processes and timelines
• Match the direction to how readers naturally scan the content

3. Use Meaningful Labels

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

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

4. Apply Consistent Styling

Use Mermaid's theming system or custom CSS to maintain visual consistency across all your diagrams. The four built-in themes are:

5. Optimize for Export Resolution

• For presentations: export at 1920x1080 or higher
• For publications: use SVG when possible, or PNG at 300+ DPI
• For web: SVG for scalability, or PNG at 2x resolution for retina displays
• For print: PDF or SVG for lossless scaling

6. Test Across Platforms

A diagram that looks perfect in the Live Editor may render differently in GitHub or VS Code. Always verify the exported image in its final destination before publishing.

For more tips on creating publication-quality diagrams, see our guide to making scientific diagrams for research papers.

Well-designed diagrams communicate complex processes clearly--whether built with Mermaid or AI-powered tools

Troubleshooting Common Issues

Diagram Not Rendering

• Check syntax: Mermaid is whitespace-sensitive. Ensure proper indentation and no extra blank lines within node definitions.
• Verify version: Some diagram types (like gitGraph) require newer Mermaid versions. Check mermaid.js.org for the latest syntax.
• Escape special characters: Characters like #, &, and < need escaping in some contexts.

Export Quality Is Low

• Use SVG instead of PNG for scalable output
• Increase the scale factor with -s 2 or -s 3 in the CLI
• Set explicit width and height to control output dimensions
• Enable transparent background to avoid white borders in dark-themed documents

CLI Fails to Install

• Ensure Node.js 18+ is installed
• Try running with npx instead of global install: npx @mermaid-js/mermaid-cli
• On Linux, you may need additional dependencies for Puppeteer (Chromium headless browser)
• Use the Docker image as a fallback: docker run --rm -v "$PWD:/data" minlag/mermaid-cli

Fonts Look Wrong in Export

• Specify fonts explicitly in your Mermaid config:

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

• Pass the config file to the CLI: mmdc -i input.mmd -o output.svg -c config.json

Frequently Asked Questions

Conclusion

Converting Mermaid diagrams to images is straightforward once you know the right tool for your situation:

1. For quick, one-off exports -- use the Mermaid Live Editor
2. For automated workflows -- use the Mermaid CLI (mmdc)
3. For IDE-integrated work -- use VS Code extensions
4. For repository documentation -- rely on GitHub or GitLab native rendering
5. For non-technical users -- use AI-powered tools like ConceptViz's Text to Diagram Generator
6. For URL-based embedding -- use the Mermaid Ink API

The method you choose depends on your workflow, technical comfort level, and how many diagrams you need to produce. For most researchers and developers, a combination of the Live Editor for quick exports and the CLI for automation covers all use cases.

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