beautiful-mermaid：让 Mermaid 图表更精美、终端更友好

GitHub: github.com/lukilabs/beautiful-mermaid
由 Craft 团队开源，用于 Craft Agents 的图表渲染

---

💡 解决了什么问题？

Mermaid 是文本图表的事实标准，但默认渲染器存在几个问题：

问题	说明
❌ 美观度不足	默认样式不够专业
❌ 主题复杂	自定义颜色需要折腾 CSS 类
❌ 无终端输出	无法生成 ASCII 格式供 CLI 使用
❌ 依赖较重	简单图表也需要引入大量代码

beautiful-mermaid 解决了以上所有问题：
- ✅ 精美的 SVG 输出
- ✅ 终端友好的 ASCII/Unicode 字符画
- ✅ 15+ 内置主题 + 支持任意 VS Code 主题
- ✅ 纯 TypeScript，无 DOM 依赖

---

🚀 核心特性

双模式输出

模式	适用场景
SVG	富 UI 界面、网页展示
ASCII/Unicode	终端环境、CLI 工具、聊天记录

5 种图表类型支持

1. 流程图 (Flowcharts) - TD/LR/BT/RL 全方向
2. 状态图 (State Diagrams)
3. 时序图 (Sequence Diagrams)
4. 类图 (Class Diagrams)
5. ER 图 (ER Diagrams)

性能

• ⚡ 超快渲染：100+ 图表在 500ms 内完成
• 🪶 零 DOM 依赖：纯 TypeScript，随处运行

---

📦 安装

npm install beautiful-mermaid
# 或
bun add beautiful-mermaid
# 或
pnpm add beautiful-mermaid

---

🎨 主题系统

双色基础模式 (Mono Mode)

最简单的主题只需两个颜色：

const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',  // 背景色
  fg: '#a9b1d6',  // 前景色
})

系统自动派生所有颜色：
- 文本 → fg 100%
- 次要文本 → fg 60% 混合 bg
- 连接线 → fg 30% 混合 bg
- 节点填充 → fg 3% 混合 bg
- 边框 → fg 20% 混合 bg

富色模式 (Enriched Mode)

提供更多自定义选项：

const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',
  fg: '#a9b1d6',
  line: '#3d59a1',    // 边/连接线颜色
  accent: '#7aa2f7',  // 箭头、高亮
  muted: '#565f89',   // 次要文本、标签
  surface: '#292e42', // 节点填充色调
  border: '#3d59a1',  // 节点描边
})

15 套内置主题

主题名	类型	背景色	强调色
zinc-light	浅色	#FFFFFF	派生
zinc-dark	深色	#18181B	派生
tokyo-night	深色	#1a1b26	#7aa2f7
tokyo-night-storm	深色	#24283b	#7aa2f7
catppuccin-mocha	深色	#1e1e2e	#cba6f7
catppuccin-latte	浅色	#eff1f5	#8839ef
nord	深色	#2e3440	#88c0d0
dracula	深色	#282a36	#bd93f9
github-light	浅色	#ffffff	#0969da
github-dark	深色	#0d1117	#4493f8
solarized-light	浅色	#fdf6e3	#268bd2
solarized-dark	深色	#002b36	#268bd2
one-dark	深色	#282c34	#c678dd

使用内置主题：

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

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

CSS 变量 = 实时切换

所有颜色通过 CSS 自定义属性控制，无需重新渲染即可切换主题：

// 实时切换主题
svg.style.setProperty('--bg', '#282a36')
svg.style.setProperty('--fg', '#f8f8f2')
// 整个图表立即更新

支持任意 VS Code 主题

通过 Shiki 集成，可直接使用数百个社区主题：

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

const highlighter = await getSingletonHighlighter({
  themes: ['vitesse-dark', 'rose-pine', 'material-theme-darker']
})

const colors = fromShikiTheme(highlighter.getTheme('vitesse-dark'))
const svg = await renderMermaid(diagram, colors)

---

💻 使用示例

SVG 输出

import { renderMermaid } from 'beautiful-mermaid'

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

ASCII 输出

import { renderMermaidAscii } from 'beautiful-mermaid'

// Unicode 模式（默认）- 更美观
const unicode = renderMermaidAscii(`graph LR; A --> B --> C`)

// 输出：
// ┌───┐     ┌───┐     ┌───┐
// │   │     │   │     │   │
// │ A │────►│ B │────►│ C │
// │   │     │   │     │   │
// └───┘     └───┘     └───┘

// ASCII 模式 - 最大兼容性
const ascii = renderMermaidAscii(`graph LR; A --> B`, { useAscii: true })

// 输出：
// +---+     +---+
// |   |     |   |
// | A |---->| B |
// |   |     |   |
// +---+     +---+

ASCII 配置选项

renderMermaidAscii(diagram, {
  useAscii: false,      // true = ASCII, false = Unicode
  paddingX: 5,          // 节点水平间距
  paddingY: 5,          // 节点垂直间距
  boxBorderPadding: 1,  // 节点内边距
})

---

🌐 浏览器使用

非打包环境可通过 CDN 引入：

<script src="https://unpkg.com/beautiful-mermaid/dist/beautiful-mermaid.browser.global.js"></script>
<script>
  const { renderMermaid, THEMES } = beautifulMermaid;
  renderMermaid('graph TD; A-->B').then(svg => { ... });
</script>

也可通过 jsDelivr 加载。

---

📊 API 参考

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

渲染 Mermaid 图表为 SVG，自动检测图表类型。

参数：
- text - Mermaid 源码
- options - 可选渲染选项

RenderOptions：

选项	类型	默认值	说明
bg	string	#FFFFFF	背景色
fg	string	#27272A	前景色
line	string?	-	边/连接线颜色
accent	string?	-	箭头、高亮
muted	string?	-	次要文本、标签
surface	string?	-	节点填充色调
border	string?	-	节点描边颜色
font	string	Inter	字体
transparent	boolean	false	透明背景

renderMermaidAscii(text, options?): string

同步渲染为 ASCII/Unicode 文本。

AsciiRenderOptions：

选项	类型	默认值	说明
useAscii	boolean	false	true=ASCII, false=Unicode
paddingX	number	5	节点水平间距
paddingY	number	5	节点垂直间距
boxBorderPadding	number	1	节点内边距

fromShikiTheme(theme): DiagramColors

从 Shiki 主题对象提取图表颜色。

THEMES: Record<string, DiagramColors>

包含所有 15 个内置主题的对象。

DEFAULTS: { bg: string, fg: string }

默认颜色 (#FFFFFF / #27272A)。

---

🔧 适用场景

• AI 辅助编程 - 在终端/聊天界面可视化数据流、状态机、系统架构
• CLI 工具 - 生成终端友好的图表输出
• 文档编写 - 快速创建美观的技术图表
• 演示文稿 - 导出精美 SVG 用于 PPT/Keynote

---

📜 许可

MIT License - 由 Craft 团队精心打造

---

整理时间：2026-02-02