将 Mermaid 图表渲染为 SVG 或 ASCII 艺术
Hacker News 摘要原标题：Render Mermaid diagrams as SVGs or ASCII art
项目简介
beautiful-mermaid 是一个高性能的工具库，旨在将 Mermaid 图表渲染为精美的 SVG 矢量图或 ASCII/Unicode 艺术字。该项目由 Craft 团队开发，专门为 AI 时代设计，具有极快的渲染速度、完全可定制的主题方案，且不依赖任何 DOM 环境。
开发背景
在 AI 辅助编程中，图表对于理解数据流、状态机和系统架构至关重要。虽然 Mermaid 是文本定义图表的行业标准，但官方渲染器在某些场景下存在局限性：审美风格较为固定、自定义主题需要复杂的 CSS 处理、不支持终端输出，且依赖包过于沉重。
beautiful-mermaid 解决了这些痛点。它的 ASCII 渲染引擎基于 Alexander Grooff 开发的 go 语言项目 mermaid-ascii，开发团队将其移植到了 TypeScript 并进行了功能扩展。
核心特性
• 支持五种图表类型：包括流程图（Flowcharts）、状态图（State Diagrams）、时序图（Sequence Diagrams）、类图（Class Diagrams）和实体关系图（ER Diagrams）。
• 双重输出格式：可生成用于富图形界面的 SVG，以及用于命令行工具或终端的 ASCII/Unicode 文本。
• 极速渲染：在不到 500 毫秒的时间内可渲染超过 100 个图表。
• 零 DOM 依赖：纯 TypeScript 编写，可以在 Node.js、浏览器或边缘计算等任何环境中运行。
• 强大的主题系统：内置 15 种精心挑选的主题，并支持实时切换。
• 单色模式：仅需背景和前景两种颜色，系统就能自动推导出完整且协调的图表配色。
• Shiki 兼容性：支持直接映射任何 VS Code 主题，实现代码高亮与图表风格的完美统一。
安装方法
可以通过主流的包管理器进行安装：
• 使用 npm 安装：npm install beautiful-mermaid
• 使用 bun 安装：bun add beautiful-mermaid
• 使用 pnpm 安装：pnpm add beautiful-mermaid
主题与配色方案
该项目的主题系统既强大又简单。
两色基础（Mono Mode）
用户只需提供背景色 bg 和前景色 fg，系统会通过 color-mix() 自动计算出其他辅助色。例如：
• 文本：100% 的前景色。
• 次要文本：60% 的前景色混合到背景色中。
• 连接器：30% 的前景色混合到背景色中。
• 节点填充：3% 的前景色混合到背景色中。
丰富模式（Enriched Mode）
如果需要更丰富的色彩，可以手动指定以下可选颜色：
• line：连线颜色。
• accent：箭头和高亮部分的颜色。
• muted：次要文本和标签颜色。
• surface：节点填充色。
• border：节点边框颜色。
内置主题
项目预设了 15 种主题，包括：zinc-light、zinc-dark、tokyo-night、catppuccin-mocha、nord、dracula、github-dark、solarized-light 等。
实时切换
所有的颜色都通过 SVG 元素上的 CSS 自定义属性（变量）实现。这意味着你可以通过 JavaScript 动态修改 --bg 或 --fg 的值，图表会立即更新颜色而无需重新渲染。
与 Shiki 集成
通过 fromShikiTheme() 函数，用户可以直接从 Shiki 高亮器中提取颜色配置。该函数会智能地将编辑器的背景、前景、注释、关键词等颜色映射到图表的相应角色中。
ASCII 与 Unicode 输出
对于终端环境，beautiful-mermaid 提供了文本渲染功能：
• Unicode 模式：默认选项，使用制表符绘制精美的框线。
• 纯 ASCII 模式：通过设置 useAscii: true 开启，使用传统的加号、减号和竖线绘制，具有最佳的兼容性。
配置选项
在渲染文本图表时，用户可以调整以下参数：
• paddingX：节点之间的水平间距，默认为 5。
• paddingY：节点之间的垂直间距，默认为 5。
• boxBorderPadding：节点方框内部的边距，默认为 1。
API 参考
• renderMermaid(text, options?)：异步函数，将 Mermaid 源码转换为 SVG 字符串。
• renderMermaidAscii(text, options?)：同步函数，将 Mermaid 源码转换为文本图表。
• fromShikiTheme(theme)：从 Shiki 主题对象中提取图表配色。
• THEMES：包含所有内置主题配置的对象。
• DEFAULTS：默认的黑白配色方案。
许可证与归属
该项目基于 MIT 许可证开源。ASCII 渲染功能借鉴了 Alexander Grooff 的工作，并在此基础上增加了时序图、类图、实体关系图的支持，以及可配置的间距和 Unicode 字符支持。