Mermaid to SVG: Practical Tips and Common Mistakes
Reviewed by the OnlineFree.app team · Updated
Key points
- Mermaid to SVG renders Mermaid code into a standalone .svg inside your browser, with no signup and nothing uploaded.
- Quote any label containing parentheses, brackets, pipes or colons, and close every subgraph with its own end line.
- Themes are baked into the exported file, so re-render whenever the destination switches between light and dark.
- On a parse error the failing line is named in red while the last good SVG stays visible.
- Copy SVG code for inline HTML; download the file for READMEs, since GitHub strips inline SVG from Markdown.
What Mermaid to SVG does in one screen
Mermaid to SVG is a browser-based renderer that turns Mermaid diagram-as-code into a standalone .svg file: paste the syntax, press Render, then download mermaid-diagram.svg or copy the markup. There is no account and no upload — parsing and rendering both happen locally in the page.
The editor accepts anything Mermaid's own parser understands — flowchart/graph, sequence, class, state, ER, gantt and pie among them — and re-renders on every edit with a short debounce of roughly 400ms, so the preview keeps up without flickering on each keystroke. The SVG scales to the width of the preview card, which is a fair preview of how it will behave in a README or a slide.
The page loads with a working flowchart already rendered. That is useful for newcomers: you get a known-good baseline to edit rather than a blank box. If you are learning the syntax, swap the labels and keep the structure — the Mermaid to SVG page is one of several browser-only utilities on OnlineFree.app.
Write Mermaid that renders on the first try
Most first-render failures come from three habits. Node labels containing parentheses, brackets, pipes or colons need double quotes — `A[Ship it (v2)]` fails where `A["Ship it (v2)"]` renders. Arrows must be `-->` or `---`, not a stray single `-` followed by `>`. And every `subgraph` needs a matching `end` on its own line.
Keep node identifiers short and ASCII (`A`, `api`, `decide`) and put the human-readable prose in the label. Identifiers that clash with keywords — a node literally called `end`, or an id that starts with a digit — are a recurring source of parse errors; rename them (`done`, `step1`) and move on.
Sequence diagrams follow the same discipline in a different shape: `Alice->>Bob: Deploy` needs its colon, and message text containing a semicolon can truncate the line. Gantt charts want `dateFormat YYYY-MM-DD` declared before the tasks. When a diagram gets long, comment out a block with `%%` and re-render to isolate the offending lines.
Pick the theme for the destination, not the preview
The dropdown offers Mermaid's built-in themes — default, neutral, dark, forest and base — and that choice is baked into the exported markup rather than applied by the page afterwards. The SVG you download therefore carries its own colours and needs no external stylesheet, but a dark-theme diagram pasted into a white wiki page will look wrong no matter how good it looked on screen.
As a rough rule: default or forest for web docs and READMEs, neutral for print and grayscale slides, dark only when the destination background is genuinely dark. If you maintain light and dark versions of the same diagram, keep two renders — adjusting CSS later will not restyle text that Mermaid positioned for a specific theme.
If the preview seems to ignore your dropdown selection, look for an `%%{init: {'theme': …}}%%` directive at the top of the code. That directive configures the renderer from inside the syntax itself; the simplest fix is to delete it and let the dropdown do the work, or set both to the same theme so preview and export agree.
Why does Mermaid report a parse error?
Nine times out of ten the cause is an unquoted special character inside a label, a bracket type that does not match (`A[x --> B[y]`), or a `subgraph` missing its `end`. Mermaid reports the line it choked on, and the tool surfaces that line number in a red message directly beneath the textarea.
Crucially, the last successful SVG stays on screen while you fix the error, so the failure is cheap: the diagram does not vanish, and you can compare broken code against the version that last rendered. Bisect by copying the working block aside, then pasting sections back one at a time until the preview breaks again.
Two less obvious triggers: an edge label containing a literal pipe inside another pair of pipes (`-->|yes|`), and copy-paste from a rich-text source that converts straight quotes into curly ones. Mermaid expects `"` — a smart quote reads as part of the label and the line falls apart.
Should you copy the SVG code or download the file?
Both buttons produce the same markup; the difference is where it ends up. Copy SVG code puts the complete `<svg>…</svg>` block on your clipboard, ready to paste inline into an HTML page, a docs template, or an email where external attachments are awkward. Styles are inline, so it renders without a linked stylesheet — but check the destination's sanitisation rules before relying on it.
As of 2026, GitHub's Markdown sanitiser strips inline SVG, so a README is better served by committing the downloaded file to the repo (say `docs/pipeline.svg`) and referencing it as an image. The download arrives as `mermaid-diagram.svg` with its `viewBox` preserved, so it stays sharp at any size; rename it to something descriptive before the second diagram arrives.
Whichever route you take, open the result where it will actually live — the README, the slide deck, the printed handout — before calling the diagram finished. Rendering differences between viewers are the most common last-minute surprise.
What the tool deliberately leaves out
This tool does one loop: code in, SVG out. It does not export PNG or PDF, does not offer custom brand colours beyond the five built-in themes, and keeps no history or tabs — reload and your syntax is gone unless you copied it somewhere. Those are deliberate omissions that keep the page to a single screen.
If a slide template refuses SVG, download the vector file and convert it with Inkscape, ImageMagick or your operating system's preview app; the original stays sharp while the raster copy is a derivative. For brand colours, either post-process the markup or move to a local Mermaid toolchain with custom theme variables — Mermaid's documentation covers the full syntax and theming options, and the W3C SVG 2 specification is the reference if you plan to hand-edit the output.
Treat the downloaded file as a source-controlled artefact rather than a screenshot: it is text, so diffs are readable, and re-rendering after a syntax change is a one-paste job. Verify important diagrams in their final destination before you ship them.
Frequently asked questions
Is Mermaid to SVG free, and is my diagram uploaded anywhere?
Yes, it is free with no signup, and no — your diagram is not uploaded. Mermaid to SVG parses and renders the code inside your browser, so the syntax you paste stays on your device. That matters for internal architecture diagrams or client work you cannot share with a third-party service. The only copy that leaves is the file you explicitly download.
Which diagram types can Mermaid to SVG render?
Mermaid to SVG renders any diagram type that Mermaid's parser supports, including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, gantt charts and pie charts. If the syntax is valid Mermaid, the tool previews it and exports a standalone SVG; invalid or unsupported syntax shows a parse error naming the failing line instead.
Why does my exported SVG look different from the preview?
The file usually matches the preview; the surrounding page does not. Mermaid to SVG bakes the selected theme's colours and fonts into the markup, so the file renders independently — a dark-theme diagram on a white wiki page or a neutral diagram on a dark slide will look off. Re-render with the theme that matches the destination.
Can I edit the downloaded SVG afterwards?
Yes. The download is plain XML text with inline styles and a preserved viewBox, so you can open it in a text editor, Inkscape, Figma or Illustrator and adjust colours, fonts or positions. Text remains as real text elements, which keeps it searchable and accessible. Hand edits are lost the next time you re-render from the Mermaid source, so keep both files.
Does Mermaid to SVG export PNG or PDF files?
No. Mermaid to SVG exports one standalone .svg file named mermaid-diagram.svg and can copy the raw SVG markup to your clipboard. For PNG or PDF, download the SVG first and convert it with Inkscape, ImageMagick or your operating system's preview app; the vector original stays sharp while the raster copy is a derivative.