mcpField
B
beautiful-mermaid

beautiful-mermaid

github.com/calesthio文档处理72.7k1.1k 次安装今天更新
代码仓库

关于 beautiful-mermaid

beautiful-mermaid 是使用 Beautiful Mermaid 将 Mermaid 图表渲染为 SVG 和 PNG 的技能，适合需要生成图表文件的 Agent。支持多种图表类型与主题，并提供 PNG 截图流程。

主要功能

  1. 01渲染 Mermaid 为 SVG
  2. 02通过截图生成 PNG
  3. 03支持五类图表
  4. 04提供多种配色主题
  5. 05包含语法与故障排查指南

适用场景

  1. 01将流程图导出为 SVG
  2. 02生成高分辨率图表 PNG
  3. 03绘制时序图或状态图

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/calesthio/openmontage --skill beautiful-mermaid

安装后在 Claude Code 中输入/beautiful-mermaid确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
mermaid-syntax.md
scripts/
create-html.ts
render.ts

详细介绍

精美的 Mermaid 图表渲染

使用 Beautiful Mermaid 库将 Mermaid 图表渲染为 SVG 和 PNG 图像。

依赖项

此技能需要 agent-browser 技能才能渲染 PNG。进行 PNG 截图前，请先加载该技能。

支持的图表类型

  • 流程图 - 处理流程、决策树、CI/CD 管道
  • 时序图 - API 调用、OAuth 流程、数据库事务
  • 状态图 - 状态机、连接生命周期
  • 类图 - UML 类图、设计模式
  • 实体关系图 - 数据库架构、数据模型

可用主题

Default、Dracula、Solarized、Zinc Dark、Tokyo Night、Tokyo Night Storm、Tokyo Night Light、Catppuccin Latte、Nord、Nord Light、GitHub Dark、GitHub Light、One Dark。

如果未指定主题，则使用 default。

常见语法模式

流程图边标签

使用管道符语法添加边标签：

A -->|label| B
A ---|label| B

避免使用空格加连字符的语法，以免渲染不完整：

A -- label --> B   # May cause issues
含特殊字符的节点标签

将含特殊字符的标签用引号括起来：

A["Label with (parens)"]
B["Label with / slash"]

工作流

步骤 1：生成或验证 Mermaid 代码

如果用户提供的是描述而非代码，请生成有效的 Mermaid 语法。完整语法详情请参阅 references/mermaid-syntax.md。

步骤 2：渲染 SVG

运行渲染脚本以生成 SVG 文件：

bun run scripts/render.ts --code "graph TD; A-->B" --output diagram --theme default

也可以从文件渲染：

bun run scripts/render.ts --input diagram.mmd --output diagram --theme tokyo-night

其他运行时：

npx tsx scripts/render.ts --code "..." --output diagram
deno run --allow-read --allow-write --allow-net scripts/render.ts --code "..." --output diagram

这会在当前工作目录中生成 <output>.svg。

步骤 3：创建 HTML 封装文件

运行 HTML 封装脚本，为截图做好准备：

bun run scripts/create-html.ts --svg diagram.svg --output diagram.html

这会创建一个简洁的 HTML 文件，用适当的内边距和背景显示 SVG。

步骤 4：使用 agent-browser 捕获高分辨率 PNG

使用 agent-browser CLI 捕获高质量截图。完整 CLI 文档请参阅 agent-browser 技能。

# Set 4K viewport for high-resolution capture
agent-browser set viewport 3840 2160

# Open the HTML wrapper
agent-browser open "file://$(pwd)/diagram.html"

# Wait for render to complete
agent-browser wait 1000

# Capture full-page screenshot
agent-browser screenshot --full diagram.png

# Close browser
agent-browser close

对于更复杂的图表，如需更高分辨率，可进一步增大视口，或在创建 HTML 封装文件时使用 --padding 选项，为图表留出更多空间。

步骤 5：清理中间文件

渲染完成后，删除所有中间文件。仅保留最终的 .svg 和 .png 文件。

需要清理的文件：

  • HTML 封装文件（例如 diagram.html）
  • 为存放图表代码而创建的任何临时 .mmd 文件
  • 渲染过程中创建的任何其他文件
rm diagram.html

如果创建了临时 .mmd 文件，也请将其删除。

输出

始终会生成两种输出：

  • SVG：矢量格式，可无限缩放，文件体积小
  • PNG：高分辨率位图，以 4K（3840×2160）视口捕获，图表宽度至少为 1200px

除非用户明确指定其他路径，否则文件会保存到当前工作目录。

主题选择指南

主题背景最适合
default浅灰色通用场景
dracula深紫色偏好深色模式
tokyo-night深蓝色现代深色风格
tokyo-night-storm更深的蓝色更高对比度
nord深色北极风格柔和、平静的视觉效果
nord-light浅色北极风格柔和色调的浅色模式
github-darkGitHub 深色与 GitHub UI 风格一致
github-lightGitHub 浅色与 GitHub UI 风格一致
catppuccin-latte暖色浅色调柔和的粉彩风格
solarized棕褐色／奶油色Solarized 配色方案
one-darkAtom 深色Atom 编辑器风格
zinc-dark中性深色简约、无明显色彩倾向

故障排除

主题未应用

检查渲染脚本的输出中的 bg 和 fg 值，或检查 SVG 的起始标签中是否包含 --bg 和 --fg CSS 自定义属性。

图表被截断或不完整
  • 检查边标签语法——使用 -->|label| 管道符表示法，而非 -- label -->
  • 确认所有节点 ID 都是唯一的
  • 检查节点标签中是否有未闭合的括号
渲染结果为空或 SVG 格式错误
  • 渲染前，请在 https://mermaid.live 验证 Mermaid 语法
  • 检查是否有需要转义的特殊字符（用引号括起来）
  • 确保已指定流程图方向（graph TD、graph LR 等）

评论

支持 Markdown