Sometimes you need a diagram as a file, for slides, a Word document, a design tool, or a platform that doesn't render Mermaid. MermaidViewer renders the export in your browser. Every plan can download PNG: 1× with a watermark on Free, up to 4× on Starter, up to 8× on Pro. JPG, SVG and PDF downloads are on Pro.
Which format should you choose?
| Format | Best for | On MermaidViewer |
|---|---|---|
| PNG | Slides, chat, email, Word | Every plan. Free 1× with a watermark. Starter up to 4×. Pro up to 8×. |
| JPG | Places that reject PNG transparency | Pro only, same scale limits as PNG |
| SVG | Websites, docs, Figma, further editing | Pro only. Vector, sharp at any size |
| Printing and reports | Pro only. Vector PDF, text stays selectable |
Exporting in the editor
- Open the editor and paste your code.
- Choose a theme (default, neutral, dark, forest or base) from the toolbar.
- Click Export. PNG is available on every plan. Pick a scale your plan allows (1×, then 2×, 3× and 4× on Starter, plus 6× and 8× on Pro) and a transparent or white background. SVG, PDF and JPG show a Pro label until you upgrade.
- Use Copy PNG to paste the image directly into Slack, Google Docs or Notion.
Need a quick conversion without the full editor? Use the dedicated Mermaid to PNG, Mermaid to SVG and Mermaid to PDF converters.
Exporting from the command line
For automation (for example in CI), the official Mermaid CLI converts files in bulk. Those commands are the CLI, not MermaidViewer plan limits. The -s 3 flag is a CLI scale, separate from the 1× / 4× / 8× caps in the app:
npx -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.svg
npx -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png -s 3 -b transparentTroubleshooting exports
- Blurry PNG — Free is locked to 1×. Starter unlocks 2×, 3× and 4×. Pro unlocks 6× and 8× in the editor.
- Black background in dark mode — choose a white background or switch to a light theme before exporting.
- Fonts look different — SVGs use the viewer's fonts; export PNG or PDF for pixel-identical output.
How the formats behave after they leave the editor
The short table above names PNG, SVG, and PDF. The part that matters when you export mermaid diagram files is what happens after the download: a slide deck, a printer, a CI job, or a screen reader.
SVG is the drawing Mermaid already made. Shapes stay shapes. Labels stay text. You can scale the file in a browser, in Figma, or in Illustrator and the edges stay sharp. The file is usually small. Use the Mermaid to SVG converter when the diagram will live on a web page or in a design tool. MermaidViewer's SVG writes labels as SVG text rather than HTML inside a foreignObject, which is why those tools can open the words instead of showing empty boxes.
PNG is pixels. A chat app, a slide template, and a Word comment all accept it. Nothing has to understand vectors. The cost is that the words are no longer text, and the sharpness is whatever scale you picked at export time. Use the Mermaid to PNG converter for that snapshot. This page is not a walkthrough of that tool. The choice is the point: pick PNG when the destination is a slot that only holds images.
PDF wraps the drawing in a page. The Mermaid to PDF converter sizes the page to the diagram, using a wide page when the chart is wide, and keeps the drawing as vectors so zoom and print don't pixelate. Text stays selectable, which matters when someone copies a service name out of a review packet. A PDF is a poor file to drop into an <img> tag. It is a good attachment on a design doc.
If two formats seem to fit, keep the SVG as the archive and generate the PNG or PDF from it when a specific tool asks. Regenerating is cheap. Redrawing because the only copy was a screenshot is not.
Background and scale
Background and scale are PNG problems first. SVG and PDF don't become blurry when a projector is wide, and they don't need a multiplier.
Scale is a pixel multiplier. On MermaidViewer the plan sets the maximum. Free PNG is 1× with a small watermark. Starter ($6.99/month or $69.90/year) includes 2×, 3×, and 4× with no watermark. Pro ($11.99/month or $119.90/year) includes 6× and 8× in the editor, and adds JPG, SVG, and PDF. The converter pages offer 1× through 4× and disable anything above the plan. JPG, SVG, and PDF downloads are Pro-only there too. The preview is free. Area grows with the square of the scale, so a 4× PNG is much larger than 1×. Check the file before you attach it to a ticket that emails a copy to the whole list.
The CLI examples below are the official mmdc tool. They do not use these plan caps. A -s 3 flag there is a CLI scale, not a MermaidViewer limit.
The CLI flag is -s. This writes a 3x PNG:
npx -p @mermaid-js/mermaid-cli mmdc -i docs/checkout.mmd -o docs/checkout.png -s 3 -b whiteLeave -s off for SVG. A scale flag doesn't add sharpness to vectors. It can add a width you didn't intend.
Background is the color behind the shapes. white is the safe default for Word, Google Docs, email, and print. Those tools often paint transparency as black, as a checkerboard, or as the dark window behind the image. transparent is what you want on a colored slide or on a site that already has a page color, so the diagram doesn't sit in a white rectangle. A hex color such as #f8fafc matches a page background when white is too stark. The flag is -b:
npx -p @mermaid-js/mermaid-cli mmdc -i docs/checkout.mmd -o docs/checkout.svg -b transparentSet the background at export time. A transparent PNG can't be "fixed" in the reader's client. If you are unsure what the destination does with alpha, export white. You can always export a second file with transparency for slides.
Theme and background interact. A dark theme on a transparent background looks correct on a dark page and disappears on a white document. Export the light theme with a white background for the document, and a separate file if the slide deck is dark. The themes guide is where you change the palette. The export only bakes in whatever palette is active.
Printing
Print the PDF or the SVG, not a 1x PNG. Printers use more dots than a screen. A PNG that looked crisp in the browser turns into gray stairs on paper. The vector PDF stays sharp, and a wide chart becomes a wide page instead of a postage stamp.
Give the file a white background before you print. Transparency has no paper color. The printer will invent one, and a dark-theme diagram printed in a hurry becomes a gray slab with light text that the toner can't hold.
Use labels, not color, for anything the reader must distinguish. A yes edge and a no edge that differ only by green and red look the same on a black-and-white printer. The words "Yes" and "No" on the arrows survive. The neutral theme is the calmer choice for a packet that will be photocopied. Bright fills waste toner and lower contrast once the color is gone.
If the diagram doesn't fit the margin, don't shrink the font to 6pt. Split it. Two flowcharts, each one scenario, print more clearly than one chart scaled until the diamonds are dots. The PDF converter already fits one diagram to one page. A chart you have to scroll sideways in the editor will be an unreadable page. Rewrite the direction to TD, or cut a subgraph into its own file, then export again.
Bind a paper review to the source. Write the file name, docs/checkout.mmd, in the footer of the doc or in the sentence above the figure. When someone marks up the paper, you can find the text to edit. The paper is not the source.
Text a person can select
Accessibility follows the format, and it also follows how you embed the file.
An SVG that is inline in the page contains text elements. A reader can select a label. Browser find often hits those words. A screen reader may reach them, though the order follows the SVG structure, which is not always the order you would read the arrows. Don't rely on that order as the only explanation. Put a sentence before the figure that states the path in prose: "The client posts to the API, the API charges the card, and the ledger write happens only after approval."
The same SVG referenced as an image, , is one image to a lot of assistive tech. The inner text is hidden. Write the alt text as a description, not as the word "diagram". "Checkout charge path from the UI through the card processor to the ledger" is useful. "Diagram" is not. Then keep the prose sentence as well. Alt text plus a paragraph covers the case where the image is skipped.
A PNG has no text layer at any scale. Scale 3 makes it sharp for sighted readers and changes nothing for a screen reader. Alt text is the whole name of the figure. If the diagram is the only place a decision is written down, the page fails for anyone who can't see the pixels. Repeat the decision in the paragraph. Link the .mmd source so someone can open the text.
PDF text from a vector export stays selectable, which helps sighted readers who search the packet. It is not a substitute for a heading structure in the document around the figure. Tag the figure in your doc tool if you have that option. The export gives you text objects. The document gives you reading order.
Contrast is part of this, not a separate polish pass. Light gray labels on a white background fail in sunlight and in print. If you baked a theme into the file, check the file, not the editor preview. Dark mode in the editor is not the PDF.
A CI job with mmdc
npx -p @mermaid-js/mermaid-cli mmdc runs the same renderer in a headless browser. The package downloads Chromium on first use unless the environment already has a browser it can launch. A locked-down CI image that blocks that download will fail before Mermaid parses anything. Allow the download, or use a runner image that already has the CLI's browser dependencies.
A minimal workflow renders on changes under docs/ and uploads the files as artifacts. Commit the SVG too if the README displays a fallback image. Don't commit a 3x PNG unless a consumer of the repo needs the pixels. The SVG is the smaller, sharper artifact.
name: diagrams
on:
push:
paths:
- "docs/**/*.mmd"
- "docs/**/*.md"
jobs:
render:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Render SVG and PNG
run: |
npx -p @mermaid-js/mermaid-cli mmdc -i docs/checkout.mmd -o docs/checkout.svg -b white
npx -p @mermaid-js/mermaid-cli mmdc -i docs/checkout.mmd -o docs/checkout.png -s 3 -b white
- uses: actions/upload-artifact@v4
with:
name: diagrams
path: docs/checkout.*Pin @mermaid-js/mermaid-cli to a version when you need last month's output to match this month's. Floating npx tracks latest, and a layout bump can move a node with no text change. The input file should contain only the diagram, no Markdown fence. checkout.mmd starts with flowchart or another keyword.
Fail the job when mmdc exits non-zero. That exit is your syntax check. It is weaker than a visual review and stronger than hoping GitHub shows a picture. Pair it with a sentence in the pull request template: open the SVG artifact, read the labels, confirm the unhappy path. The renderer will not notice that you drew the wrong service.
flowchart LR
MMD[checkout.mmd] --> MMDC[mmdc]
MMDC --> SVG[checkout.svg]
MMDC --> PNG["checkout.png at 3x"]Keep one command in the README so a teammate can regenerate without reading the workflow. The flags worth documenting are -i, -o, -b, and -s for PNG. Everything else can wait until a font or a config file actually needs to change.
Getting from a snippet to a picture, including the errors that block it, is mermaid code to diagram.