Beautiful Mermaid Diagram Rendering

Render Mermaid diagrams as SVG (for UIs) or ASCII/Unicode (for terminals and markdown).

Quick Start

1. Install Dependencies

npm install beautiful-mermaid

Or run the setup script:

bash scripts/setup.sh

2. Render SVG

import { renderMermaid } from 'beautiful-mermaid'

const svg = await renderMermaid(`
  graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
`)

3. Render ASCII

import { renderMermaidAscii } from 'beautiful-mermaid'

const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)
// Output:
// +---+     +---+     +---+
// | A |---->| B |---->| C |
// +---+     +---+     +---+

Core API

renderMermaid(text, options?): Promise<string>

Returns SVG string. Options:

renderMermaidAscii(text, options?): string

Returns ASCII/Unicode string. Synchronous. Options:

Theming

Mono Mode (Two Colors)

Provide only bg and fg. All other colors are derived automatically:

const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',
  fg: '#a9b1d6'
})

Built-in Themes

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

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

Available 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 Theme Integration

import { getSingletonHighlighter } from 'shiki'
import { renderMermaid, fromShikiTheme } from 'beautiful-mermaid'

const highlighter = await getSingletonHighlighter({
  themes: ['vitesse-dark']
})
const colors = fromShikiTheme(highlighter.getTheme('vitesse-dark'))
const svg = await renderMermaid(diagram, colors)

See themes.md for complete theming reference.

Supported Diagrams

Common Patterns

Save SVG to File

import { renderMermaid, THEMES } from 'beautiful-mermaid'
import { writeFile } from 'fs/promises'

const svg = await renderMermaid(diagram, THEMES['github-dark'])
await writeFile('diagram.svg', svg)

Generate ASCII for Markdown

import { renderMermaidAscii } from 'beautiful-mermaid'

const ascii = renderMermaidAscii(diagram, { useAscii: true })
const markdown = `## Architecture\n\n\`\`\`\n${ascii}\n\`\`\``

Live Theme Switching (Browser)

SVG output uses CSS custom properties. Switch themes without re-rendering:

svgElement.style.setProperty('--bg', '#282a36')
svgElement.style.setProperty('--fg', '#f8f8f2')

Reference Files

Troubleshooting

"Cannot find module 'beautiful-mermaid'": Run npm install beautiful-mermaid

Empty SVG output: Verify Mermaid syntax is valid. Test at mermaid.live first.

Fonts not rendering: Ensure the font is available. Use web-safe fonts or embed font CSS.