How to Convert Mermaid to SVG, Step by Step
Reviewed by the OnlineFree.app team · Updated
Key points
- Mermaid to SVG converts diagram-as-code into a standalone .svg file entirely in the browser, with nothing uploaded.
- The preview re-renders roughly 400ms after you stop typing, so you can iterate without pressing Render each time.
- Five built-in themes — default, neutral, dark, forest and base — are baked into the exported markup, not linked externally.
- Parse errors name the failing line while the last good SVG stays visible, which makes debugging far quicker.
- The download is mermaid-diagram.svg with inline styles and a preserved viewBox, so it scales cleanly in docs and slides.
What Mermaid to SVG actually does
Mermaid to SVG converts Mermaid diagram-as-code into a standalone SVG file, and it performs that conversion entirely inside your browser tab. You paste Mermaid syntax, the page renders it as real inline SVG, and you download the markup as a single file. Nothing is uploaded to a server, and there is no signup step.
The input is one monospace textarea that accepts any Mermaid diagram type: flowchart, sequence, class, state, ER, gantt and pie. The page loads pre-filled with a working flowchart — a `graph TD` with a start node, a decision diamond and two branches — so you can see a rendered diagram before typing anything.
The output is a live preview card plus two actions: Download SVG, which saves a standalone file named mermaid-diagram.svg with inline styles and the viewBox preserved, and Copy SVG code, which puts the markup on your clipboard. Because styles are inlined, the file does not depend on a stylesheet sitting next to it.
Render your first diagram in five steps
Start by opening Mermaid to SVG and leaving the example in place until you have seen one successful render. That baseline matters: if your own paste fails later, you already know the page and your browser are fine.
Step two is replacing the textarea contents with your own code, starting with the diagram type keyword (`graph TD`, `sequenceDiagram`, `classDiagram`, `erDiagram`, `gantt`, `pie`). Step three is choosing a theme from the dropdown if the default does not match its destination. Step four is pressing Render, or simply pausing — the preview re-renders about 400ms after you stop typing, so rapid edits do not thrash the page.
Step five is exporting. Use Download SVG for a file to commit to a repository or drop into a slide deck, and Copy SVG code when you want to paste the markup directly into an HTML template or a CMS block. Both actions read from the same rendered result, so what you downloaded is exactly what you saw.
How do you pick a theme for the exported SVG?
The theme dropdown applies one of Mermaid's five built-in themes — default, neutral, dark, forest and base — and the choice is baked into the exported markup. Pick for the destination, not for the preview: a dark diagram dropped into a white wiki page will look like a hole in the document.
As a rule of thumb we use default for light documentation and READMEs, dark for dark-mode slide decks, neutral for anything destined for print or PDF, and forest when a client's palette is already green. Base is the stripped-back option that leaves the most room if you plan to override colours with your own CSS after export.
If the diagram lives in two places at once — a light docs site and a dark deck — render it twice and keep both files. The theme lives inside the SVG rather than in an external stylesheet, so two exports really are two self-contained assets with no shared dependency.
Read the error message, not the diagram
When Mermaid cannot parse your code, the page shows an inline red message under the textarea that names the failing line as Mermaid reports it, and the last good SVG stays visible instead of blanking out. That behaviour is deliberate: you can compare the broken code above with the last working render below.
Most failures come from a handful of causes. Node labels containing parentheses, brackets or colons need surrounding quotes — `A[Ship it (v2)]` breaks, `A["Ship it (v2)"]` works. The lowercase word `end` inside a flowchart label ends the block early. Sequence diagrams break when a participant is used before it is declared, and a missing direction after `graph` (as in plain `graph` with no TD, LR, BT or RL) fails outright.
Change one thing at a time and re-render. The debounced preview makes it tempting to rewrite a whole block, but if you do, you lose track of which edit fixed it — and you will usually need that knowledge on the next diagram.
Where a downloaded SVG works, and where it doesn't
An SVG with inline styles and a preserved viewBox scales cleanly from a 200px sidebar thumbnail to a full-width slide without regeneration; that is the main reason to prefer it over a raster screenshot. It also stays crisp when someone zooms a PDF export of your docs.
Two honest caveats. First, text inside the SVG is real text laid out by Mermaid, not a font embedded in the file, so a viewer without the same fonts will render with its own substitution — check the file in a second browser before you ship it. Second, many platforms sanitise SVG: GitHub renders SVG in Markdown but strips scripts and remote resources, and some CMS media libraries refuse SVG uploads altogether.
When a platform rejects the file, paste the markup inline into your HTML instead, or link to the .svg as an image and let the browser handle it. The W3C's SVG specification is the reference for what a standalone document requires, and the Mermaid documentation covers syntax for every diagram type. Neither is required reading to use the tool — but both save time when a diagram misbehaves. For other quick conversions with the same no-upload approach, see the rest of OnlineFree.app.
Frequently asked questions
Does Mermaid to SVG upload my diagram code to a server?
No. Mermaid to SVG renders your code client-side in the browser, so the diagram text never leaves your machine and no account is needed. That makes it safe for internal architecture diagrams and anything under an NDA, though you should still treat the page like any other website and avoid pasting secrets such as credentials or customer data into labels.
What file does Mermaid to SVG download, and can I edit it afterwards?
It downloads a standalone .svg file named mermaid-diagram.svg with styles inlined and the viewBox preserved. Because it is plain SVG, you can open it in any vector editor or a text editor and change colours, fonts and spacing by hand. Re-rendering from Mermaid overwrites those manual edits, so keep your source code if you plan to iterate.
Which Mermaid diagram types does Mermaid to SVG support?
Any diagram Mermaid itself can parse: flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, gantt charts and pie charts, since the tool passes your code straight to Mermaid's renderer. If a newer Mermaid diagram type is not supported, the red error message under the textarea will tell you rather than producing a blank preview.
Why does my diagram show an error instead of rendering?
The most common cause is unquoted punctuation inside a node label, such as parentheses or a colon, which needs wrapping in double quotes. Other frequent culprits are the lowercase word end used as a label, a missing direction after graph, and participants referenced before declaration in a sequence diagram. The inline message names the failing line, and the last successful SVG stays visible for comparison.
Can I use the exported SVG in a GitHub README?
Yes, GitHub renders SVG images in Markdown, and an SVG with inline styles and no remote resources is the safest kind to commit. Note that GitHub sanitises SVG and strips scripts, so interactivity will not survive, and font substitution may change text width. Open the downloaded file locally first to confirm it looks right before committing it.