pretty-mermaid

Pretty Mermaid

使用随附的 Node.js CLI 创建或渲染 Mermaid 图表。使用 SVG 制作可缩放的文档，使用 PNG 便于分享或供仅支持栅格图像的使用方使用，使用 ASCII 或 Unicode 在终端和纯文本中显示。

工作目录

将此文件所在目录视为 <skill-root>。从该目录运行随附脚本，或使用绝对路径调用脚本。将用户源文件和渲染输出保存在用户指定的位置；不要将渲染器复制到用户的项目中。

工作流

1. 确定用户是否提供了 Mermaid 源码，还是需要根据文字描述编写图表。
2. 根据下表选择图表类型和输出格式。
3. 仅在需要了解语法、主题选择或 API 行为的更多细节时，阅读相关参考文件。
4. 将新源码保存为 .mmd 文件，并保留用户使用的术语和关系。
5. 使用指定主题或显式颜色进行渲染。
6. 检查结果。修复语法错误、裁切、布局拥挤或标签不清晰等问题，然后重新渲染。
7. 返回源文件和输出文件的路径，以及所选格式和主题。

除非用户要求替换，否则不要覆盖现有源文件或输出文件。

选择图表类型

需求	图表类型	起始代码
流程、决策树、架构	流程图	flowchart LR
API 调用、消息、交互	时序图	sequenceDiagram
生命周期或有限状态机	状态图	stateDiagram-v2
类、模块、关系	类图	classDiagram
数据库实体和基数	ER 图	erDiagram
柱形、折线、趋势、对比	XY 图表	xychart-beta

编写较复杂的 Mermaid 语法时，请阅读 references/DIAGRAM_TYPES.md。

选择输出格式

输出	适用场景	说明
SVG	README、文档、幻灯片、网站	可缩放、支持主题和透明背景
PNG	聊天、预览、仅支持栅格图像的工具	设置 --format png；无需外部转换器
Unicode	现代终端和易读的文本预览	默认 ASCII 渲染器输出
纯 ASCII	日志和受限终端	添加 --use-ascii
ANSI 彩色文本	交互式终端	设置 --color-mode

核心命令

在 <skill-root> 目录中运行这些命令。

列出主题

node scripts/themes.mjs

渲染 SVG

node scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.svg \
  --theme tokyo-night

渲染终端文本

node scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.txt \
  --format ascii \
  --color-mode none

当 Unicode 框线字符不适用时，添加 --use-ascii。

渲染 PNG

node scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.png \
  --format png \
  --width 1200 \
  --theme tokyo-night

批量渲染目录

node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./rendered \
  --format svg \
  --theme github-dark \
  --workers 4

当需要渲染三个或更多图表，或需要对整个目录应用一致的选项时，请使用批量渲染。

选择主题

• 通用深色文档：tokyo-night
• GitHub 深色或浅色界面：github-dark、github-light
• 打印和演示文稿：zinc-light
• 高对比度配色：dracula
• 冷色、克制的配色：nord、nord-light

当视觉主题选择很重要时，请阅读 references/THEMES.md 或打开 docs/THEME_GALLERY.md。可以使用显式颜色标志微调指定主题。

实用选项

通用样式

选项	用途
--theme <name>	应用 15 种内置主题之一
--bg、--fg	设置必需的基础颜色
--line、--accent、--muted	微调连接线、强调色和次要文本
--surface、--border	微调节点填充色和描边
--font <name>	设置 SVG 字体系列

SVG

选项	用途
--transparent	移除 SVG 背景
--padding <n>	设置画布内边距
--node-spacing <n>	设置节点水平间距
--layer-spacing <n>	设置层级垂直间距
--component-spacing <n>	分隔不相连的组件
--interactive	为 XY 图表启用悬停提示

PNG

选项	用途
--width <n>	设置输出宽度为 100 到 10000 像素，同时保持宽高比
--transparent	保留透明背景

终端输出

选项	用途
--use-ascii	将 Unicode 框线替换为纯 ASCII 字符
--padding-x、--padding-y	调整图表间距
--box-border-padding	调整节点框内部的内边距
--color-mode <mode>	none、auto、ansi16、ansi256、truecolor 或 html

运行 node scripts/render.mjs --help 或 node scripts/batch.mjs --help，查看权威的 CLI 选项列表。

编写指南

• 优先使用简短、具体的标签；保留用户提供的领域专有术语。
• 当分支或消息含义不明确时，使用明确的边标签。
• 将无关内容拆分，而不是缩小文字，以确保大型图表易于阅读。
• 宽流程使用 LR，窄文档使用 TB。
• 避免只通过颜色传达含义。
• 打印时使用浅色主题，并确认其与最终背景的对比度。
• 对于不熟悉的语法，请从 assets/example_diagrams/ 开始，并查阅图表参考。

验证

渲染后：

1. 确认命令成功退出，且输出文件非空。
2. 确认 SVG 输出以 <svg 开头；确认 PNG 输出可作为有效图像打开；确认文本输出包含可见的图表内容。
3. 在布局重要时检查视觉输出，尤其是长标签、CJK 文本、断开的组件和 XY 图表。
4. 确认箭头、基数、状态和标签与源请求一致。
5. 报告渲染器的限制，而不是悄悄丢弃不受支持的语法。

修改此技能、其脚本、模板或参考资料时，请同时运行 npm test 和 npm run validate。

故障排除

• 缺少依赖项：在 <skill-root> 中运行 npm install；CLI 也会尝试在首次运行时安装依赖项。
• 未知主题：运行 node scripts/themes.mjs，并使用列表中的确切名称。
• 解析错误：查阅 references/DIAGRAM_TYPES.md，将内容缩减至出错语句，然后逐步恢复图表。
• SVG 过于拥挤：增大 --node-spacing、--layer-spacing 或 --component-spacing。
• PNG 颜色错误：自定义颜色请使用具体的十六进制值；未解析的外部 CSS 变量无法栅格化。
• 重定向输出中的终端颜色转义码：使用 --color-mode none。

参考资料索引

资源	何时阅读或使用
references/DIAGRAM_TYPES.md	编写或调试 Mermaid 语法时
references/THEMES.md	比较主题或定义自定义颜色时
references/api_reference.md	扩展脚本或直接调用 beautiful-mermaid 时
docs/THEME_GALLERY.md	通过视觉效果选择主题时
assets/example_diagrams/	从受支持的图表模板开始时
scripts/render.mjs	渲染单个图表时
scripts/batch.mjs	并行渲染目录时
scripts/themes.mjs	列出已安装的主题时