mcpField
B
beautiful-mermaid

beautiful-mermaid

github.com/intellectronica设计与 UI2981.8k 次安装27 周前更新
代码仓库

关于 beautiful-mermaid

beautiful-mermaid 是用于生成和渲染 Mermaid 图表的技能，可输出 SVG 和 PNG。它支持多种图表类型与主题，并通过浏览器截图生成 PNG。

主要功能

  1. 01生成 Mermaid 语法
  2. 02渲染 SVG 图表
  3. 03捕获高分辨率 PNG
  4. 04支持五种图表类型
  5. 05选择多种主题

适用场景

  1. 01说明流程与决策路径
  2. 02记录 API 调用或事务
  3. 03展示状态机
  4. 04制作 UML 或数据库图表

安装

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

$npx skills add https://github.com/intellectronica/agent-skills --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