SuperAPI AI Directory

beautiful-mermaid

Coding & development

View repository

Updated 10-15 23:25

About this skill

Beautiful Mermaid

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-mermaid in Node, browser, or CLI tooling.
  • Troubleshoot diagram rendering, spacing, or theme output.

Scenario Map (Use-Case Examples)

  • Terminal/CLI output diagram: Use renderMermaidAscii() with useAscii: true for 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 add accent/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

  1. Install beautiful-mermaid in the target project.
  2. Use renderMermaid() for SVG or renderMermaidAscii() for terminal output.
  3. 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 renderMermaid from the package.
  • Pass Mermaid source text (auto-detects diagram type).
  • Provide optional RenderOptions for 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: true for pure ASCII compatibility.
  • Adjust paddingX, paddingY, and boxBorderPadding to 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 bg and fg to 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, border to 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 THEMES and 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 examples
  • references/api-ascii.md: renderMermaidAscii parameter table, pitfalls, and examples
  • references/themes-and-shiki.md: theme model, built-in themes, and Shiki integration