pretty-mermaid

Pretty Mermaid

使用一条命令渲染精美、专业风格的 Mermaid 图表。支持用于网页/文档的 SVG 和用于终端的 ASCII。

快速开始

渲染单个图表

从文件：

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

从用户提供的 Mermaid 代码：

1. 将代码保存到 .mmd 文件
2. 使用所需主题运行渲染脚本

批量渲染多个图表

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

ASCII 输出（终端友好）

node scripts/render.mjs \
  --input diagram.mmd \
  --format ascii \
  --use-ascii

---

工作流决策树

步骤 1：用户想要什么？

• 渲染现有 Mermaid 代码 → 转到渲染
• 创建新图表 → 转到创建
• 应用/更改主题 → 转到主题
• 批量处理 → 转到批量渲染

步骤 2：选择输出格式

• SVG（网页、文档、演示文稿）→ --format svg
• ASCII（终端、日志、纯文本）→ --format ascii

步骤 3：选择主题

• 深色模式文档 → tokyo-night（推荐）
• 浅色模式文档 → github-light
• 鲜艳色彩 → dracula
• 查看所有主题 → 运行 node scripts/themes.mjs

---

渲染图表

从文件

当用户提供 .mmd 文件或 Mermaid 代码块时：

1. 保存到文件（如果是代码块）：

   cat > diagram.mmd << 'EOF'
   flowchart LR
       A[Start] --> B[End]
   EOF
   

2. 使用主题渲染：

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

3. 验证输出：

   • SVG：在浏览器中打开或嵌入文档
   • ASCII：在终端中显示

输出格式

SVG（可缩放矢量图形）

• 最佳用途：网页、文档、演示文稿
• 特性：全色支持、透明、可缩放
• 用法：--format svg --output diagram.svg

ASCII（终端艺术）

• 最佳用途：终端输出、纯文本日志、README 文件
• 特性：纯文本，随处可用，无依赖
• 用法：--format ascii（输出到 stdout）
• 选项：
  • --use-ascii - 使用纯 ASCII（无 Unicode）
  • --padding-x 5 - 水平间距
  • --padding-y 5 - 垂直间距

高级选项

自定义颜色（覆盖主题）：

node scripts/render.mjs \
  --input diagram.mmd \
  --bg "#1a1b26" \
  --fg "#a9b1d6" \
  --accent "#7aa2f7" \
  --output custom.svg

透明背景：

node scripts/render.mjs \
  --input diagram.mmd \
  --transparent \
  --output transparent.svg

自定义字体：

node scripts/render.mjs \
  --input diagram.mmd \
  --font "JetBrains Mono" \
  --output custom-font.svg

---

创建图表

使用模板

步骤 1：列出可用模板

ls assets/example_diagrams/
# flowchart.mmd  sequence.mmd  state.mmd  class.mmd  er.mmd

步骤 2：复制并修改

cp assets/example_diagrams/flowchart.mmd my-workflow.mmd
# 根据用户需求编辑 my-workflow.mmd

步骤 3：渲染

node scripts/render.mjs \
  --input my-workflow.mmd \
  --output my-workflow.svg \
  --theme github-dark

图表类型参考

有关详细语法和最佳实践，请参阅 DIAGRAM_TYPES.md。

快速参考：

流程图 - 流程、工作流、决策树

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

时序图 - API 调用、交互、消息流

sequenceDiagram
    User->>Server: Request
    Server-->>User: Response

状态图 - 应用状态、生命周期、FSM

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading
    Loading --> [*]

类图 - 对象模型、架构、关系

classDiagram
    User --> Post: creates
    Post --> Comment: has

ER 图 - 数据库模式、数据模型

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains

根据用户需求

步骤 1：确定图表类型

• 流程/工作流 → 流程图
• API/交互 → 时序图
• 状态/生命周期 → 状态图
• 对象模型 → 类图
• 数据库 → ER 图

步骤 2：创建图表文件

cat > user-diagram.mmd << 'EOF'
# [插入生成的 Mermaid 代码]
EOF

步骤 3：渲染并迭代

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

# 与用户一起审查，根据需要编辑 diagram.mmd，重新渲染

---

主题

列出可用主题

node scripts/themes.mjs

输出：

Available Beautiful-Mermaid Themes:

 1. zinc-light
 2. zinc-dark
 3. tokyo-night
 4. tokyo-night-storm
 5. tokyo-night-light
 6. catppuccin-mocha
 7. catppuccin-latte
 8. nord
 9. nord-light
10. dracula
11. github-dark
12. github-light
13. solarized-dark
14. solarized-light
15. one-dark

Total: 15 themes

主题选择指南

对于深色模式文档：

• tokyo-night ⭐ - 现代，开发者友好
• github-dark - 熟悉的 GitHub 风格
• dracula - 鲜艳，高对比度
• nord - 冷色调，极简

对于浅色模式文档：

• github-light - 干净，专业
• zinc-light - 高对比度，适合打印
• catppuccin-latte - 温暖，友好

详细主题信息： 参见 THEMES.md

将主题应用于图表

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

比较主题

使用多个主题渲染同一图表：

for theme in tokyo-night dracula github-dark; do
  node scripts/render.mjs \
    --input diagram.mmd \
    --output "diagram-${theme}.svg" \
    --theme "$theme"
done

---

批量渲染

批量渲染目录

步骤 1：组织图表

diagrams/
├── architecture.mmd
├── workflow.mmd
└── database.mmd

步骤 2：批量渲染

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

输出：

Found 3 diagram(s) to render...
✓ architecture.mmd
✓ workflow.mmd
✓ database.mmd

3/3 diagrams rendered successfully

批量处理多种格式

同时渲染 SVG 和 ASCII：

# SVG 用于文档
node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./svg \
  --format svg \
  --theme github-dark

# ASCII 用于 README
node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./ascii \
  --format ascii \
  --use-ascii

性能选项

• --workers N - 并行渲染（默认：4）
• 推荐：--workers 8 用于 10 个以上图表

---

常见用例

1. 文档架构图

# 用户提供架构描述
# → 创建 flowchart.mmd
# → 使用专业主题渲染

node scripts/render.mjs \
  --input architecture.mmd \
  --output docs/architecture.svg \
  --theme github-dark \
  --transparent

2. API 时序图

# 用户描述 API 流程
# → 创建 sequence.mmd
# → 使用清晰主题渲染

node scripts/render.mjs \
  --input api-flow.mmd \
  --output api-sequence.svg \
  --theme tokyo-night

3. 数据库模式可视化

# 用户提供表定义
# → 创建 er.mmd
# → 渲染用于数据库文档

node scripts/render.mjs \
  --input schema.mmd \
  --output database-schema.svg \
  --theme dracula

4. 终端友好工作流

# 用于 README 或终端显示
node scripts/render.mjs \
  --input workflow.mmd \
  --format ascii \
  --use-ascii > workflow.txt

5. 演示幻灯片

# 高对比度，适用于投影仪
node scripts/render.mjs \
  --input slides-diagram.mmd \
  --output presentation.svg \
  --theme zinc-light

---

故障排除

beautiful-mermaid 未安装

Error: Cannot find module 'beautiful-mermaid'

注意： 首次运行时应自动安装。如果失败：

cd /path/to/pretty-mermaid-skill && npm install

无效的 Mermaid 语法

Error: Parse error on line 3

解决方案：

1. 对照 DIAGRAM_TYPES.md 验证语法
2. 在 https://mermaid.live/ 上测试
3. 检查常见错误：
   • A --> B 中缺少空格
   • 节点形状语法错误
   • 未闭合的括号

文件未找到

Error: Input file not found: diagram.mmd

解决方案： 确认文件路径正确，必要时使用绝对路径

---

资源

scripts/

可执行的 Node.js 脚本，用于渲染操作：

• render.mjs - 主要渲染脚本
• batch.mjs - 批量处理脚本
• themes.mjs - 主题列表工具

references/

用于指导图表创建的文档：

• THEMES.md - 详细主题参考及示例
• DIAGRAM_TYPES.md - 所有图表类型的综合语法指南
• api_reference.md - beautiful-mermaid API 文档

assets/

用于快速创建图表的模板文件：

• example_diagrams/flowchart.mmd - 流程图模板
• example_diagrams/sequence.mmd - 时序图模板
• example_diagrams/state.mmd - 状态图模板
• example_diagrams/class.mmd - 类图模板
• example_diagrams/er.mmd - ER 图模板

---

提示与最佳实践

性能

• 3 个以上图表使用批量渲染（并行处理）
• 保持图表节点少于 50 个以获得快速渲染
• 使用 ASCII 进行快速预览

质量

• 技术文档使用 tokyo-night 或 github-dark
• 添加透明度以兼容深色/浅色模式：--transparent
• 在批量渲染前在目标环境中测试主题

工作流

1. 从 assets/example_diagrams/ 中的模板开始
2. 根据用户反馈迭代
3. 最后应用主题
4. 如果需要，同时渲染 SVG（文档）和 ASCII（README）

可访问性

• 演示文稿使用高对比度主题
• 为所有连接添加文本标签
• 避免仅依赖颜色编码信息