The best Mermaid viewer is the one that doesn't fight you (so I built one)

I write a lot of Mermaid. Architecture notes, PR descriptions, the diagram in my last post. And for a while my workflow was: write the code, paste it somewhere, squint at a red error that said "Parse error on line 7", count to line 7 by hand, fix a missing arrow, export a PNG with a transparent background that vanished the moment I dropped it into a dark-mode doc. Repeat.

So I did the reasonable, proportionate thing and built my own Mermaid viewer.

What is a Mermaid viewer, anyway?

Mermaid is a text format for diagrams. You write something like this:

flowchart LR
    Idea --> Code --> Bug --> Coffee --> Code

and a Mermaid viewer (also called a Mermaid previewer, renderer or live editor) turns it into an actual diagram. GitHub, GitLab, Notion and Obsidian all render Mermaid inside Markdown now, so the same few lines of text become a diagram in your README, your docs and your wiki without anyone opening a drawing app.

The viewer is where you write and debug that text before it goes anywhere. Which means its job is mostly to tell you, quickly and kindly, what you got wrong.

What makes a Mermaid viewer actually good?

After far too many hours of diagram-driven procrastination, here's my checklist. If a tool misses more than one of these, I stop using it.

• Live preview. The diagram updates as you type. Not when you click a button. Not after a page reload.
• Errors that point somewhere. "Syntax error" is a vibe. "Syntax error, line 7, highlighted" is help.
• Keeps the last good diagram on screen. Typing a half-finished arrow shouldn't blank the whole preview.
• Pan and zoom. A 40-node flowchart doesn't fit in a sidebar. Being able to drag around and zoom in is the difference between reading it and guessing.
• Clean exports. SVG for docs and slides, PNG for places that refuse SVG (looking at you, half of the internet).
• Looks good by default. The stock theme is fine. "Fine" is not what you want in a design review.
• Private. Architecture diagrams describe your systems. They shouldn't need to leave your laptop.
• Requires an account. No.

How do the popular Mermaid viewers compare?

There's no single "best" for everyone, so here's my honest take on where each one shines. All of these are good tools. I still use some of them.

Why did I build another one?

Because every time I used a Mermaid viewer I wanted roughly 80% of one tool and 20% of another. And as established in previous posts, I have a well-documented inability to leave a small itch unscratched.

The specific annoyances, as a bug report I filed against my own patience:

BUG-001: Preview goes blank every time I type an incomplete line
BUG-002: Error says "line 7", editor does not say which one is line 7
BUG-003: Big diagram, small pane, no zoom
BUG-004: Exported PNG has a transparent background; disappears in dark mode
BUG-005: Default theme looks like a 2009 intranet
Status:  WONTFIX (upstream)  →  FIXED (built my own)

How does my Mermaid previewer work?

It's a split screen. Code on the left, diagram on the right, a draggable divider in the middle so you can give whichever side more room. Here's what happens every time you type:

flowchart LR
    A[You type Mermaid code] --> B{Paused for 350 ms?}
    B -- no --> A
    B -- yes --> C[Mermaid renders in your browser]
    C --> D{Valid?}
    D -- yes --> E[Show the new diagram]
    D -- no --> F[Keep the last good diagram]
    F --> G[Highlight the broken line and explain the error]
    E --> H[Export as SVG or PNG]

(Yes, that diagram is rendered by the same engine. Hit the expand button in its corner and it opens in the previewer. More on that below.)

The bits I'm quietly proud of:

• Live rendering that waits about a third of a second after you stop typing, so it isn't redrawing on every keystroke.
• Line-level errors. When Mermaid complains about a line, that line gets highlighted in the editor and the full error shows up underneath. The status bar flips from "Rendered" to "Syntax error" so you notice.
• The last good diagram stays put while you're mid-edit. No flashing white panes.
• Pan and zoom on a proper canvas. Drag to pan, Ctrl + scroll (or pinch on a trackpad) to zoom, plus zoom buttons and a "fit to screen" button for when you've lost the diagram somewhere off to the left.
• A diagram-type badge on the file tab, so you can see at a glance that it's reading your code as a Flowchart, Sequence, ER diagram, Gantt and so on.
• Examples to start from: flowchart, sequence, entity relationship, state machine and Gantt. Pick one and edit.
• Copy button for the code, and a line and character count, because I like numbers.

Does it support every Mermaid diagram type?

It runs the real Mermaid library (version 12), so if Mermaid supports it, the previewer renders it. That includes:

How do I export a Mermaid diagram as SVG or PNG?

This is the part I rebuilt the most, so it gets its own section.

1. Open the Mermaid previewer and write or paste your code.
2. Wait for the status bar to say Rendered.
3. Click SVG or PNG in the export pill at the top right of the preview.

That's it. A few details that matter more than they sound:

• SVG is the diagram exactly as Mermaid drew it. Scales forever, tiny file, best for docs, slides and anything printed.
• PNG is drawn at 2x resolution from the diagram itself, not from your screen, so your current pan and zoom don't leak into the export. It also gets a solid background that matches the theme, so it won't disappear when someone pastes it into a dark Slack channel.
• Labels are drawn as plain SVG text rather than embedded HTML. Mermaid's default HTML labels can break PNG export in browsers, and I'd rather the button just worked.

Why do the diagrams look nicer than the default?

Because I couldn't help myself. The previewer uses a custom theme on top of Mermaid's base theme: soft pastel fills with a stronger border in the same colour, rounded corners, a barely-there shadow, slightly heavier text and dashed group outlines. Light and dark mode get separately tuned palettes so text keeps its contrast on both.

You don't have to do anything to get it. Your diagram code stays plain, portable Mermaid, so it'll still render on GitHub or anywhere else. It just looks better while it's here.

Is it safe to paste private diagrams into an online Mermaid viewer?

In mine, yes, because nothing leaves your browser. Mermaid is loaded into the page and renders locally. There's no server rendering step, no account and no database of your diagrams. It also runs Mermaid in its strict security mode, which sanitises the output and blocks the click-handler and script tricks Mermaid otherwise allows.

Can I open a diagram from a blog post in the viewer?

Yes, and this is my favourite small feature. Every Mermaid diagram on this blog has an expand button in its corner. Click it and the exact code opens in the previewer in a new tab, ready to pan, zoom, edit or export.

sequenceDiagram
    participant R as You, reading a post
    participant B as Blog diagram
    participant P as Mermaid previewer
    R->>B: Click the expand button
    B->>P: Open with the code in the URL fragment
    Note over P: The fragment never reaches the server
    P-->>R: Live, editable diagram

The code rides along in the URL fragment (the bit after #), which browsers don't send to servers. So even the handoff is private. Try it on either diagram in this post.

FAQ

What is the best Mermaid viewer?

For quick, private editing with good exports, a browser-based viewer with live preview, line-level errors, pan and zoom, and SVG and PNG export. My free Mermaid previewer is built around exactly that. For team collaboration and saved diagrams, Mermaid Chart is the better fit. For sharing editable links, use the official Mermaid Live Editor.

Is there a free online Mermaid viewer?

Yes. The Mermaid previewer on this site is free, needs no sign-up and runs in your browser. The official Mermaid Live Editor is free too.

How do I preview Mermaid code without installing anything?

Paste it into an online Mermaid viewer. Open the previewer, paste your code into the left pane and the diagram appears on the right within half a second.

How do I convert Mermaid to PNG or SVG?

Render the diagram in the previewer, then click PNG or SVG in the export controls. PNGs export at 2x resolution with a solid background.

Why won't my Mermaid diagram render?

Usually a typo on one line: a missing arrow (-->), an unclosed bracket, a reserved word like end used as a node name or the wrong diagram keyword on the first line. The previewer highlights the line Mermaid complains about and shows the full error below the editor.

Does the viewer work offline?

Once the page and Mermaid have loaded, rendering happens entirely in your browser and doesn't call a server. You'll need a connection to load it the first time.

Can I use it for Mermaid diagrams in GitHub READMEs?

Yes. Write and fix the diagram in the previewer, then paste the code into a ```mermaid block in your README. GitHub will render it with its own theme.

Want to try it?

Open the Mermaid previewer, pick an example from the dropdown and break it on purpose. That's honestly the fastest way to see what it does. If you'd rather keep browsing, there's a small pile of other free tools on the site: a diff checker, an LLM token cost calculator and a few more, all running in your browser.

Found a diagram it renders badly, or have a feature you want? Email me at siddhant06137@gmail.com or find me on X as @creatorsidd. And if your team needs a small custom tool like this one, book a 15-minute call. I build those for clients too.