I wanted cleaner beautiful Mermaid diagrams for docs, so I made a small exporter

river jiang — Thu, 04 Jun 2026 07:56:46 +0000

I use Mermaid diagrams a lot when I am trying to explain something that is easier to see than to read.

A release flow. A service talking to another service. A small state machine. The kind of diagram that belongs in a README, an architecture note, or a planning doc.

Mermaid itself is great for that. Plain text, versionable, reviewable. The part that kept annoying me was what happened after the diagram looked right.

I often wanted a clean image for a README, a slide, or a blog post. Not a rough screenshot. Not something with awkward padding. Not a diagram that looked fine in one place and slightly blurry everywhere else.

So I made a small tool for that:

Mermaid Online

It is a browser-based Mermaid editor and exporter. Paste Mermaid code, preview it, adjust the export style, then download PNG, SVG, JPG, WebP, or PDF.

No signup. No watermark. The core render/export workflow happens in the browser.

The problem I wanted to smooth out

Here is a tiny example:

flowchart LR
  A[Write the doc] --> B[Sketch the flow]
  B --> C[Preview the diagram]
  C --> D[Export for README]
  C --> E[Export for slides]

That is easy enough to write.

But when I need to put it somewhere, I usually start making small judgement calls:

Should this be SVG or PNG?
Does it need a transparent background?
Is 1x too soft for a slide?
How much padding should the diagram have?
Will it still be readable in a GitHub README?

None of these are hard problems. That is partly why they are annoying. They are small enough that I do not want to open a design tool, but visible enough that a sloppy export makes the whole doc feel less cared for.

What Mermaid Online does

The tool is intentionally simple.

You paste or edit Mermaid code on the left, check the live preview, then choose the export format and style.

The formats I cared about most:

PNG for README files, docs, and slides
SVG when I want a vector asset
PDF for handoff or document workflows
WebP for lightweight blog images
JPG when I need the boring compatible option

There are also presets for common destinations: clean docs, GitHub README, transparent backgrounds, dark docs, slides, and blog-style cards.

That last bit matters more than I expected. A diagram for a README and a diagram for a presentation usually should not have exactly the same padding, background, and scale.

A workflow that feels right to me

For documentation, I usually do this:

Write the Mermaid diagram directly while working on the doc.
Paste it into Mermaid Online.
Use a docs or README preset.
Export PNG at 2x, or SVG if the destination handles it well.
Put both the Mermaid source and exported asset near the doc.

For slides, I usually switch to a transparent preset and export at a larger scale. That keeps labels and arrows sharper on big screens, especially when the diagram gets resized by the slide tool.

For blog posts, WebP is nice when I want something lighter, and the editorial-style preset gives the diagram enough breathing room that it does not look like a raw screenshot dropped into the middle of the page.

Why local-first mattered

Some Mermaid diagrams are harmless. Others describe internal systems, database relationships, release flows, or security-review details.

I did not want the default workflow to require uploading diagram text just to turn it into an image.

The core editor and exporter run in the browser, so the diagram content stays local during the normal export path. That makes the tool feel more appropriate for architecture notes and internal docs.

It is still a small project, so I am being careful with the wording here: this is an independent tool, not affiliated with Mermaid.js, Mermaid Chart, or their maintainers.

What I would like to improve next

The current version is mostly about single-diagram export quality.

The things I keep thinking about next are:

Batch export from Markdown files
ZIP downloads for multiple diagrams
Saved custom themes
Better workflows for docs teams
More examples for common architecture and product diagrams

I am deliberately not rushing all of that in at once. The first version should do one job well: turn Mermaid code into a clean asset you can actually use.

Try it

If you use Mermaid in README files, technical docs, slides, or blog posts, you can try it here:

https://mermaidonline.org/

I would especially like feedback from people who write docs often:

Which export format do you use most?
Do you prefer keeping Mermaid source in the doc, or committing generated images?
What diagram style actually looks good inside your documentation system?

Small tools get better when they are shaped by real workflows, so practical feedback is more useful to me than general praise.