Beautiful‑Mermaid: 超高速、全主题可用的 Mermaid 图表渲染器

February 20, 2026

类别: 实用开源项目

标签:

Open Source SVG TypeScript mermaid diagram-rendering

Beautiful‑Mermaid: 超高速、全主题可用的 Mermaid 图表渲染器

Beautiful‑Mermaid 是一款极小、纯 TypeScript 的库，可将 Mermaid‑DSL 转化为精美的 SVG 或终端友好的 ASCII 艺术，且占用空间极小。它是 Craft Agents 图表支持的引擎，能在 500 毫秒内渲染 100+ 图表，提供 15 款现成主题，并支持无缝的基于 CSS 的实时主题切换。

主要特点

零 DOM 依赖 – 纯 TS，支持 Node、浏览器或 CLI。
快速渲染 – 超轻量打包，500 毫秒内渲染 100+ 图表。
双重输出 – SVG 供丰富 UI 使用，ASCII/Unicode 供终端使用。
丰富主题 – 双色单色模式、增色模式、15 款内置主题、Shiki 集成。
实时主题切换 – CSS 自定义属性，无需重新渲染。
多图表支持 – 流程图、状态图、序列图、类图和 ER 图。

快速开始

# 通过你喜欢的包管理器安装
npm i beautiful-mermaid
# 或
bun add beautiful-mermaid
# 或
pnpm add beautiful-mermaid

渲染 SVG

import { renderMermaid } from 'beautiful-mermaid';

const diagram = `
sequenceDiagram
Alice->>Bob: Hello Bob!
Bob-->>Alice: Hi Alice!
`;

const svg = await renderMermaid(diagram, {
  // 你可以选择预制主题
  ...THEMES['tokyo-night'],
  // 或自定义颜色方案
  bg: '#1a1b26',
  fg: '#a9b1d6',
});

document.body.innerHTML = svg;

在 CLI 中渲染 ASCII

import { renderMermaidAscii } from 'beautiful-mermaid';

const ascii = renderMermaidAscii(`graph LR; A --> B --> C`);
console.log(ascii);

┌───┐ ┌───┐ ┌───┐
│ A │────►│ B │────►│ C │
└───┘ └───┘ └───┘

用 CSS 变量自定义主题

所有主题颜色都是位于 <svg> 根元素上的 CSS 自定义属性，能够实现即时的实时切换：

svg.style.setProperty('--bg', '#282a36');
svg.style.setProperty('--fg', '#f8f8f2');

SVG 会立即更新，无需重新渲染。

集成 Shiki 主题

若你喜欢 VS Code 风格的主题，只需导入 Shiki 主题并转换：

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

const highlighter = await getSingletonHighlighter({
  themes: ['dracula', 'catppuccin-mocha'],
});

const colors = fromShikiTheme(highlighter.getTheme('dracula'));
const svg = await renderMermaid(diagram, colors);

示例：渲染流程图

const flow = `
flowchart TD
  Start --> Decide{Decision}
  Decide -->|Yes| Process
  Decide -->|No| End
`;

const svg = await renderMermaid(flow, THEMES['one-dark']);

为什么选择 Beautiful‑Mermaid？

简洁 – 无繁重依赖，纯 TS。
性能 – 基准测试显示 100+ 图表 < 500 ms。
通用性 – 适用于 Web、Node 或任何环境。
可扩展 – 可自定义主题，与 Shiki 集成，颜色实时切换。
开源 – MIT 许可证，社区友好。

使用场景

开发工具 – 在 VS Code 扩展中嵌入交互式流程图。
文档 – 为 MkDocs 或 Docsify 生成 SVG 图表。
CLI 工具 – 在终端日志中打印人性化图表。
聊天机器人 – 当用户请求图表帮助时，视觉化逻辑。

社区与贡献

Beautiful‑Mermaid 是 GitHub 上一个活跃的项目。欢迎通过 issue 和 pull request 进行贡献。查看 issues 线程了解未完成任务，或查看贡献指南。

TL;DR

安装 beautiful-mermaid。
调用 renderMermaid() 生成 SVG，或 renderMermaidAscii() 生成文本。
使用内置主题或自定义颜色。
用 CSS 变量实时切换主题。
利用 Shiki 获得 VS Code 主题配色。

使用 Beautiful‑Mermaid，你可以把普通 Mermaid 文本转换为惊艳的视觉体验——无论是浏览器、终端，还是你需要的任何地方。

原创文章: 查看原文

分享本文