| name | beautiful-mermaid |
| description | Render Mermaid diagrams as SVG, PNG, or ASCII art via the `bm` CLI. Use when the user asks to render, visualize, or generate a flowchart, sequence diagram, ER diagram, state diagram, class diagram, gantt chart, or any Mermaid graph. |
beautiful-mermaid
Render Mermaid diagrams to SVG, PNG, or terminal ASCII through the bm CLI from beautiful-mermaid-cli.
When to use
- The user wants to render a Mermaid diagram (
graph, flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, …) to an image file.
- The user pastes Mermaid source and asks for a rendered visual.
- The user wants ASCII / Unicode box-drawing output for a diagram in the terminal.
- The user asks to render with a specific font, or to know which fonts are available — first call
bm fonts --json to enumerate the system, then pass --font <family> (or --font-file <path>) to bm render.
Prerequisites
Confirm the bm binary, fonts, and PNG WASM runtime are usable before rendering programmatically:
bm doctor --json
If bm is missing: npm i -g beautiful-mermaid-cli (or brew install okooo5km/tap/bm).
Core commands
bm render -c '<mermaid source>' -o out.svg
bm render -c '<mermaid source>' -o out.png --theme dracula --scale 2
bm ascii -c '<mermaid source>'
bm themes
bm fonts --json --filter cjk
bm render -c '<mermaid source>' -o out.png --font 'Source Han Sans CN'
bm render -c '<mermaid source>' -o out.png --font 'Inter' --font-mono 'JetBrains Mono'
bm render -c '<mermaid source>' -o out.png --font-file /path/to/MyFont.ttf
Font semantics differ between SVG and PNG:
- SVG:
--font is baked into the markup as a font-family declaration. The
reader (browser, editor) needs that font installed to see it. --font-mono
and --font-file are ignored for SVG. Emoji and CJK render as long as the
reader has matching system fonts — this almost always works.
- PNG:
bm resolves the font on the local system, embeds rasterized glyphs.
All three flags participate in resvg's per-glyph fallback, so mixed CJK/Latin
diagrams render correctly even when the chosen font has only Latin coverage.
PNG emoji: glyphs missing, surrounding text intact
PNG output cannot render emoji glyphs — resvg-wasm does not implement
COLRv1 (Noto Color Emoji, Twemoji, Segoe UI Emoji v2) or sbix (Apple Color
Emoji). Emoji codepoints in the input render as blank space in the PNG.
The good news: surrounding Latin / CJK text renders correctly. bm
loads the OS-bundled emoji font (Apple Color Emoji on macOS, Noto Color
Emoji on Linux, Segoe UI Emoji on Windows) into fontBuffers purely as
a shaping shim — its presence claims the emoji codepoints in cmap, which
prevents them from corrupting the per-glyph fallback for nearby CJK
characters. Without the shim, mixed [🚀 中文] text would render entirely
as tofu boxes.
bm render -o foo.png emits a one-shot stderr warning when the input
contains emoji.
SVG output preserves emoji — the viewer renders them via system fonts.
If a user asks to render emoji:
- Strongly prefer
bm render -o foo.svg.
- If they need PNG specifically, warn them emoji glyphs will be missing
(surrounding text is fine), or suggest rendering to SVG first then
rasterizing with a real-text-engine tool (Inkscape, librsvg, Chrome
headless).
bm fonts --filter emoji lists emoji fonts the system has — useful
awareness but does not change PNG output.
Source may also come from a file (bm render diagram.mmd ...) or stdin (cat x.mmd | bm render -o out.svg).
For programmatic / agent use
Every subcommand accepts --json for a stable, machine-readable contract (schema_version: 1):
- Success payloads → stdout; error payloads → stderr. Never mixed.
- Exit codes:
0 success, 1 WASM/unclassified, 2 usage, 3 parse, 4 I/O.
- PNG cannot be inlined in JSON — always pass
-o <file> for PNG output.
bm render --json -c 'graph LR\n A-->B' -o out.svg
bm themes --json
bm ascii --json -c 'graph LR\n A-->B'
bm fonts --json --filter cjk
Deep reference
See reference.md for the full flag table, the 15-theme list, and the --json schema summary.
