Learn-skills.dev beautiful-mermaid

Skill for using the beautiful-mermaid TypeScript library to render Mermaid diagrams to SVG or ASCII/Unicode, apply themes (including Shiki), and integrate in Node or browser contexts.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/994ak/beautiful-mermaid-skill/beautiful-mermaid" ~/.claude/skills/neversight-learn-skills-dev-beautiful-mermaid && rm -rf "$T"

manifest: data/skills-md/994ak/beautiful-mermaid-skill/beautiful-mermaid/SKILL.md

source content

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

Install
```
beautiful-mermaid
```
in the target project.
Use
```
renderMermaid()
```
for SVG or
```
renderMermaidAscii()
```
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
```
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 集成