beautiful-mermaid

Render Mermaid diagrams to SVG or ASCII using the doc-mermaid-ascii npm package. Zero DOM dependencies, 15 built-in themes, works in Node.js/Bun without a browser.

Prerequisites

npm install beautiful-mermaid
# or
bun add beautiful-mermaid

Quick Render

Use the bundled render script for one-shot rendering:

# SVG output (default)
node ~/.claude/skills/beautiful-mermaid/scripts/render.mjs diagram.mmd -o diagram.svg

# ASCII output
node ~/.claude/skills/beautiful-mermaid/scripts/render.mjs diagram.mmd --ascii

# With theme
node ~/.claude/skills/beautiful-mermaid/scripts/render.mjs diagram.mmd -o diagram.svg --theme tokyo-night

# From inline text
node ~/.claude/skills/beautiful-mermaid/scripts/render.mjs --inline "graph LR; A --> B --> C" --ascii

# From stdin
echo "graph TD; A --> B" | node ~/.claude/skills/beautiful-mermaid/scripts/render.mjs --ascii

Programmatic API

SVG Rendering (async)

import { renderMermaid, THEMES } from 'beautiful-mermaid'

// Default (white bg, dark fg)
const svg = await renderMermaid('graph TD\n  A --> B')

// With theme
const svg = await renderMermaid(diagram, THEMES['tokyo-night'])

// Custom colors (mono mode — just 2 colors)
const svg = await renderMermaid(diagram, { bg: '#1a1b26', fg: '#a9b1d6' })

// Enriched colors
const svg = await renderMermaid(diagram, {
  bg: '#1a1b26', fg: '#a9b1d6',
  line: '#3d59a1', accent: '#7aa2f7', muted: '#565f89',
})

ASCII Rendering (sync)

import { renderMermaidAscii } from 'beautiful-mermaid'

// Unicode box-drawing (default)
const text = renderMermaidAscii('graph LR\n  A --> B --> C')
// ┌───┐     ┌───┐     ┌───┐
// │ A │────►│ B │────►│ C │
// └───┘     └───┘     └───┘

// Pure ASCII
const text = renderMermaidAscii('graph LR\n  A --> B', { useAscii: true })
// +---+     +---+
// | A |---->| B |
// +---+     +---+

Supported Diagram Types

5 types (use the existing doc-mermaid skill's syntax references for full syntax):

Type	Header	SVG	ASCII
Flowchart	graph TD / flowchart LR	Yes	Yes
State	stateDiagram-v2	Yes	Yes
Sequence	sequenceDiagram	Yes	Yes
Class	classDiagram	Yes	Yes
ER	erDiagram	Yes	Yes

For C4, Gantt, timeline, user journey, mindmap, pie, git graph — use the doc-mermaid skill with mmdc instead.

Theming

See references/themes.md for the full theme catalog.

Mono Mode (2 colors)

Provide just bg and fg. All other colors auto-derive via color-mix():

• Text: fg at 100%
• Secondary text: fg at 60%
• Edge labels: fg at 40%
• Connectors: fg at 30%
• Arrow heads: fg at 50%
• Node fill: fg at 3%
• Node stroke: fg at 20%

Built-in Themes

import { THEMES } from 'beautiful-mermaid'
// THEMES['tokyo-night'], THEMES['dracula'], THEMES['github-dark'], etc.

15 themes: zinc-light, zinc-dark, tokyo-night, tokyo-night-storm, tokyo-night-light, catppuccin-mocha, catppuccin-latte, nord, nord-light, dracula, github-light, github-dark, solarized-light, solarized-dark, one-dark

Shiki VS Code Theme

import { fromShikiTheme } from 'beautiful-mermaid'
const colors = fromShikiTheme(shikiHighlighter.getTheme('vitesse-dark'))

RenderOptions

Option	Type	Default	Description
bg	string	#FFFFFF	Background color
fg	string	#27272A	Foreground/text color
line	string?	derived	Edge/connector color
accent	string?	derived	Arrow heads, highlights
muted	string?	derived	Secondary text, labels
surface	string?	derived	Node fill tint
border	string?	derived	Node stroke
font	string	Inter	Font family
padding	number	40	Canvas padding (px)
nodeSpacing	number	24	Horizontal node spacing
layerSpacing	number	40	Vertical layer spacing
transparent	boolean	false	Transparent background

AsciiRenderOptions

Option	Type	Default	Description
useAscii	boolean	false	ASCII chars vs Unicode box-drawing
paddingX	number	5	Horizontal node spacing
paddingY	number	5	Vertical node spacing
boxBorderPadding	number	1	Padding inside node boxes

When to Use This vs doc-mermaid Skill

Need	Use
SVG/ASCII for flowchart, sequence, class, state, ER	doc-mermaid-ascii
C4, Gantt, timeline, journey, mindmap, pie, git graph	doc-mermaid (mmdc)
Terminal/ASCII output	doc-mermaid-ascii
Editor-themed diagrams (tokyo-night, dracula, etc.)	doc-mermaid-ascii
Server-side rendering without Puppeteer	doc-mermaid-ascii
Full Mermaid syntax compatibility	doc-mermaid (mmdc)