Overview
Enable fast, themeable Mermaid rendering in Node, browser, or CLI outputs using the beautiful-mermaid package. Use this skill to generate SVG diagrams, ASCII/Unicode diagrams, and consistent theming.
When To Use
- Render Mermaid diagrams to SVG or ASCII/Unicode.
- Add or customize themes (two-color base, enrichment colors, or Shiki themes).
- Integrate
beautiful-mermaidin Node, browser, or CLI tooling. - Troubleshoot diagram rendering, spacing, or theme output.
Scenario Map (Use-Case Examples)
- Terminal/CLI output diagram: Use
renderMermaidAscii()withuseAscii: truefor pure ASCII. - Make the terminal prettier: Use
renderMermaidAscii()default Unicode for box-drawing. - Web page/React component: Use
renderMermaid()to get SVG and inject into DOM. - Need theme consistency: Use
THEMES['...']to apply a built-in theme. - Need company brand colors: Provide
bg+fg(mono) or addaccent/muted/surface. - Need to match the VS Code theme: Use Shiki +
fromShikiTheme(). - CDN/no-bundler environment: Use the browser global bundle via
<script>tag. - Need real-time skin switching: Update SVG CSS variables (
--bg,--fg) without re-render.
Scenario examples (by audience)
Programmers/Engineers
- CLI/terminal output diagram: Use
renderMermaidAscii()+ ASCII compatible
import { renderMermaidAscii } from 'beautiful-mermaid'
const ascii = renderMermaidAscii('graph LR; A-->B', { useAscii: true })
- Web/React embedded SVG: Use
renderMermaid()to generate an SVG string
import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid('graph TD; A-->B')
- CI/documentation generation: Batch-render SVG files
import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid('sequenceDiagram\nA->>B: ping')
- Theme consistency: Use a built-in theme or custom colors
import { renderMermaid, THEMES } from 'beautiful-mermaid'
const svg = await renderMermaid('graph TD; A-->B', THEMES['tokyo-night'])
Non-technical users
- Operations/product documentation: Export SVG to embed in documents
import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid('graph TD; A-->B')
- Unified style for meetings/presentations: Use theme colors to stay consistent
import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid('graph TD; A-->B', { bg: '#0f0f0f', fg: '#e0e0e0' })
- Courses/demos: Display ASCII/Unicode in the terminal
import { renderMermaidAscii } from 'beautiful-mermaid'
const unicode = renderMermaidAscii('graph LR; A-->B')
- Design consistency: Use Shiki themes to map the editor style
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('graph TD; A-->B', colors)
Quick Start
- Install
beautiful-mermaidin the target project. - Use
renderMermaid()for SVG orrenderMermaidAscii()for terminal output. - Apply a built-in theme or custom colors.
import { renderMermaid, renderMermaidAscii, THEMES } from 'beautiful-mermaid'
const svg = await renderMermaid('graph TD; A-->B', THEMES['tokyo-night'])
const ascii = renderMermaidAscii('graph LR; A-->B', { useAscii: true })
Tasks
Render SVG
- Import
renderMermaidfrom the package. - Pass Mermaid source text (auto-detects diagram type).
- Provide optional
RenderOptionsfor colors, font, and transparency.
import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid(`
sequenceDiagram
Alice->>Bob: Hello
`, {
bg: '#1a1b26',
fg: '#a9b1d6',
accent: '#7aa2f7',
transparent: false,
font: 'Inter'
})
Render ASCII/Unicode
- Import
renderMermaidAscii. - Use
useAscii: truefor pure ASCII compatibility. - Adjust
paddingX,paddingY, andboxBorderPaddingto tune spacing.
import { renderMermaidAscii } from 'beautiful-mermaid'
const unicode = renderMermaidAscii('graph LR; A-->B')
const ascii = renderMermaidAscii('graph LR; A-->B', { useAscii: true })
Theme With Two Colors
- Provide only
bgandfgto use mono mode. - Let the library derive all other colors with
color-mix().
const svg = await renderMermaid('graph TD; A-->B', {
bg: '#0f0f0f',
fg: '#e0e0e0'
})
Theme With Enrichment Colors
- Add any of:
line,accent,muted,surface,borderto override derivations. - Supply only the enrichments that matter.
const svg = await renderMermaid('graph TD; A-->B', {
bg: '#1a1b26',
fg: '#a9b1d6',
accent: '#7aa2f7',
line: '#3d59a1',
muted: '#565f89',
surface: '#292e42',
border: '#3d59a1'
})
Use Built-in Themes
- Import
THEMESand pass one of the 15 preset themes.
import { renderMermaid, THEMES } from 'beautiful-mermaid'
const svg = await renderMermaid('graph TD; A-->B', THEMES['tokyo-night'])
Use Shiki Themes
- Load a Shiki theme with
getSingletonHighlighter. - Convert it with
fromShikiTheme. - Pass converted colors to
renderMermaid.
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('graph TD; A-->B', colors)
Browser Script Tag Usage
- Use the CDN global bundle.
- Access exports on
beautifulMermaid.
<script src="https://unpkg.com/beautiful-mermaid/dist/beautiful-mermaid.browser.global.js"></script>
<script>
const { renderMermaid, THEMES } = beautifulMermaid
renderMermaid('graph TD; A-->B', THEMES['tokyo-night']).then(svg => {
// use svg
})
</script>
Live Theme Switching
- Update SVG CSS custom properties (no re-render required).
svg.style.setProperty('--bg', '#282a36')
svg.style.setProperty('--fg', '#f8f8f2')
Troubleshooting
- If render fails, validate Mermaid syntax and diagram type.
- For terminal alignment, prefer Unicode or set
preserveDisplayWidth: true. - For browser usage, ensure the global bundle is loaded before use.
Resources
- Reference API details and theme lists in
references/beautiful-mermaid-reference.md. references/api-render.md: renderMermaid parameter table, pitfalls, and examplesreferences/api-ascii.md: renderMermaidAscii parameter table, pitfalls, and examplesreferences/themes-and-shiki.md: theme model, built-in themes, and Shiki integration