Mermaid in READMEs: live preview and SVG export without CLI

Published: 2026-09-05

How Mermaid fenced diagrams work in GitHub READMEs, common flowchart and sequence patterns, and how to preview and export SVG or PNG locally in the browser without a Mermaid CLI install.

Mermaid turns a small text dialect into diagrams: flowcharts, sequence diagrams, class diagrams, and more. On GitHub (and many other hosts), you can drop Mermaid into a README inside a fenced code block with language mermaid, and the platform renders it for readers.

Authoring is still awkward if you only push and wait for the remote preview. Syntax errors are easy; themes on GitHub may not match what you want in slides; and sometimes you need a static SVG or PNG for a wiki that does not run Mermaid at all. A local Mermaid live editor runs mermaid.js in your browser—paste source, see SVG, copy or download—without installing the Mermaid CLI or uploading diagram source.

Mermaid in a GitHub README

GFM-style hosts typically recognize a fence like this:

```mermaid
flowchart LR
  A[Clone] --> B[Build]
  B --> C[Deploy]
```

Readers see a diagram; the raw file stays plain text, so diffs stay reviewable. That is the same “docs as code” idea as keeping AsciiDoc or Markdown in the repo: the source is the source of truth.

Not every Markdown surface supports Mermaid. Chat paste boxes, strict CommonMark renderers, and some static generators need a plugin or a pre-rendered image. When the host will not run Mermaid, export SVG (or PNG) from a local preview and commit or link that asset instead.

Diagram types you will use most

Mermaid has many diagram kinds. For READMEs and architecture notes, three cover most cases:

Type	Keyword	Good for
Flowchart	`flowchart` (or legacy `graph`)	Pipelines, decision trees, “how this repo is laid out”
Sequence	`sequenceDiagram`	Request paths, auth handshakes, who calls whom
Class	`classDiagram`	Small domain models, module relationships

Example flowchart (top-down):

flowchart TD
  Start([Start]) --> Input[/Enter data/]
  Input --> Check{Valid?}
  Check -->|Yes| Process[Process]
  Check -->|No| Error[Show error]
  Process --> End([Done])
  Error --> Input

Example sequence sketch:

sequenceDiagram
  participant U as User
  participant API as API
  U->>API: POST /orders
  API-->>U: 201 Created

Direction on flowcharts matters: TD / TB (top-down), LR (left-right), RL, BT. Prefer the direction that matches how readers scan the README section.

Keep diagrams small. A 40-node flowchart in a README is hard to read on mobile and painful in PR diffs. Link out to a longer architecture doc if you need depth.

Live preview without the CLI

The official Mermaid CLI (@mermaid-js/mermaid-cli) and editor plugins are fine for CI image generation. For a quick edit loop on a secret or unfinished diagram, a browser tool is enough:

Paste Mermaid source into the Mermaid live editor.
Wait for the short debounce; the preview updates with mermaid.js in the tab.
Pick a theme (default, dark, neutral, forest) to approximate docs or slides.
Use starter chips (flowchart, sequence, class) when you need a skeleton.
Switch between Rendered and SVG source; copy SVG, download SVG, or download PNG.

Drafts can persist in local storage on your device only. Nothing is uploaded to LocalTools—useful when the diagram still names unreleased services or internal hosts. See why local-only tools matter.

Complex diagrams may take a moment to render. A parse or layout error appears as a render error in the tool; fix the source and the preview recovers.

SVG vs PNG export

Format	When to prefer it
SVG	Docs, wikis, and slides that can embed vector graphics; scales cleanly
PNG	Surfaces that only accept raster images; quick chat or ticket attachments

PNG export rasterizes the SVG preview. For crisp scaling in documentation, prefer SVG download. If PNG fails (canvas or size limits), download SVG and convert elsewhere if you must.

Embedding SVG in Markdown varies by host. GitHub READMEs often work best with Mermaid fences or with an image file (.svg / .png) referenced with a normal image link—not always with inline raw SVG. Match the pattern your host documents.

If you later turn SVG into React components for a site, see SVG to React cleanup.

README workflow that stays reviewable

Draft in Mermaid source — Keep the fence in the README (or a linked .md) so reviewers can suggest text edits.
Preview locally before push — Catch syntax errors without a CI round-trip.
Export only when needed — Use SVG/PNG for non-Mermaid surfaces; otherwise keep the fence so future edits stay textual.
Diff the source, not only the image — Binary PNG diffs are opaque; Mermaid text diffs are readable. Compare versions with a text diff when cleaning up labels.

Theme in the live editor is for preview and export. GitHub’s Mermaid theme is controlled by the platform (and user dark/light mode), not by a theme line inside every fence. Do not assume your Forest export will look identical on github.com.

Common pitfalls

Unsupported diagram type on the host — A new Mermaid feature may work in mermaid.js locally but not yet in GitHub’s renderer. If the README fails to render, simplify or export an image.
HTML or script inside labels — Prefer plain text labels. Odd characters can break parsing; escape carefully or rephrase.
Assuming every Markdown tool supports Mermaid — Preview in the target host or ship SVG.
Huge auto-layout graphs — Split into two diagrams or a high-level plus detail page.
Uploading proprietary architecture to public Mermaid sandboxes — Prefer local-only preview when the diagram is sensitive.
Editing only the PNG — You lose the editable Mermaid source; keep the text unless the surface cannot render it.

Try it locally

Open the Mermaid live editor:

Paste a small flowchart or sequenceDiagram (or load an example chip).
Switch themes and confirm the SVG source tab looks right.
Copy SVG or download SVG/PNG for a non-Mermaid destination.

For surrounding README prose and tables, pair with a Markdown live editor or the Markdown table formatter. Processing stays in your browser.