994ak/beautiful-mermaid

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 输出图：Use renderMermaidAscii() with useAscii: true for pure ASCII.
• 终端更美观：Use renderMermaidAscii() default Unicode for box-drawing.
• Web 页面/React 组件：Use renderMermaid() to get SVG and inject into DOM.
• 需要主题一致：Use THEMES['...'] to apply a built-in theme.
• 需要公司品牌色：Provide bg + fg (mono) or add accent/muted/surface.
• 需要跟 VS Code 主题一致：Use Shiki + fromShikiTheme().
• CDN/无打包环境：Use the browser global bundle via <script> tag.
• 需要实时换肤：Update SVG CSS variables (--bg, --fg) without re-render.

场景举例（按人群）

程序员/工程师

• CLI/终端输出图：Use renderMermaidAscii() + ASCII 兼容

import { renderMermaidAscii } from 'beautiful-mermaid'
const ascii = renderMermaidAscii('graph LR; A-->B', { useAscii: true })

• Web/React 内嵌 SVG：Use renderMermaid() 生成 SVG 字符串

import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid('graph TD; A-->B')

• CI/文档生成：批量渲染 SVG 文件

import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid('sequenceDiagram\nA->>B: ping')

• 主题统一：Use 内置主题或自定义颜色

import { renderMermaid, THEMES } from 'beautiful-mermaid'
const svg = await renderMermaid('graph TD; A-->B', THEMES['tokyo-night'])

非技术用户

• 运营/产品文档：导出 SVG 嵌入文档

import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid('graph TD; A-->B')

• 会议/汇报统一风格：用主题色保持一致

import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid('graph TD; A-->B', { bg: '#0f0f0f', fg: '#e0e0e0' })

• 课程/演示：终端内展示 ASCII/Unicode

import { renderMermaidAscii } from 'beautiful-mermaid'
const unicode = renderMermaidAscii('graph LR; A-->B')

• 设计一致性：用 Shiki 主题映射编辑器风格

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 参数表、误区与示例
• references/api-ascii.md: renderMermaidAscii 参数表、误区与示例
• references/themes-and-shiki.md: 主题模型、内置主题与 Shiki 集成