mermaid-to-gif

技能：Mermaid 转 GIF

将 Mermaid 图表转换为带有丰富动画效果的 GIF。支持 .mmd 文件，也支持从 .md 文件中提取 ```mermaid 代码块。

前置条件：FFmpeg、Python 3.8+、Playwright（pip install playwright && playwright install chromium）

---

使用场景

• 用户想将 Mermaid 图表转换为动画 GIF
• 用户有包含 Mermaid 代码块的 .mmd 文件或 .md 文件
• 用户需要用于演示文稿、文档或社交媒体的动画视觉内容
• 用户想批量转换文档中的所有 Mermaid 代码块

---

根据上下文选择样式

重要：转换 .md 文件中的 Mermaid 代码块时，请阅读周围的 Markdown 上下文，为每个图表选择最合适的动画样式。不要对所有代码块都盲目应用相同的样式。

决策指南

1. 阅读每个 Mermaid 代码块周围的 Markdown 文本——理解图表所展示的内容
2. 根据语义选择样式：

上下文线索	推荐样式	原因
数据管道、ETL 流、请求/响应路径	pulse-flow	流动的虚线能够表现数据移动
架构分层、组织结构图、层级关系	progressive	元素逐层激活
分步流程、教程演示	highlight-walk	聚光效果引导读者逐步浏览
系统概览、标题图表、简单参考图	wave	亮度波纹增添动感，又不会分散注意力
包含消息流的时序图	progressive	消息按对话顺序逐条激活
类图/ER 图（参考/静态）	progressive 或 wave	结构逐渐亮起或出现柔和的波纹效果

3. 考虑特殊情况：

   • 如果周围文本提到“数据从 A 流向 B”，即使是简单的流程图，也要使用 pulse-flow
   • 如果文本描述了“三层”或“两级”，使用 progressive 逐层激活
   • 如果图表用于装饰或补充说明，使用 wave，保持简洁
   • 对于非常大或复杂的图表，优先使用 wave 或缩短 --duration，以合理控制 GIF 文件大小

4. 按代码块覆盖样式：批量处理 .md 文件时，可能需要使用不同样式多次运行脚本，并提取指定代码块。也可以使用合适的默认样式处理整个文件，然后重新处理需要特殊效果的单个代码块。

示例：根据上下文进行处理

## Data Ingestion Pipeline        ← context: "pipeline" → pulse-flow
[mermaid block: graph LR with ETL stages]

## System Architecture            ← context: "architecture" → progressive
[mermaid block: graph TD with layers]

## Quick Reference                ← context: "reference" → wave
[mermaid block: simple diagram]

---

默认工作流

单个 .mmd 文件

python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd

包含 Mermaid 代码块的 Markdown 文件

python <skill-root>/scripts/mermaid_to_gif.py document.md -o ./images/

这会提取所有 ```mermaid 代码块，并为每个代码块生成一个 GIF。

多个文件

python <skill-root>/scripts/mermaid_to_gif.py *.mmd -o ./gifs/
python <skill-root>/scripts/mermaid_to_gif.py doc1.md doc2.md -o ./gifs/

替换 Markdown 中的 Mermaid 代码块

生成 GIF 后，将原始的 ```mermaid 代码块替换为图像引用：

![Flow Diagram](images/document-1.gif)

根据图表内容使用描述性的替代文本。图像路径应为相对于 Markdown 文件的路径。

---

动画样式

所有样式都能让图表从第 1 帧起完整可见——没有任何元素会一开始就隐藏，也不会从完全透明开始淡入。每种样式都会添加动态效果，同时让用户始终能看到完整的图表结构。

样式	效果	适用场景
progressive（默认）	所有元素初始亮度较低（25% 不透明度），然后依次激活至全亮；边缘通过描边动画逐步绘制	流程图、架构图、层级结构
highlight-walk	所有元素初始亮度较低（15%）；带蓝色光晕的聚光效果逐个扫过元素，经过的元素会保持明亮	分步流程、教程
pulse-flow	所有元素始终完全可见；边缘变为流动的虚线（虚线大小和速度统一）	数据流、管道、请求路径
wave	所有元素始终完全可见；亮度脉冲与蓝色光晕波纹依次扫过各元素	简单图表、概览、参考图

动画详情

• progressive：元素从 25% 不透明度开始（图表结构始终可见）。节点、边和标签按交错顺序（节点 → 边 → 节点 → 边）沿流程方向依次激活。边使用 stroke-dashoffset 实现绘制效果。激活速度很快（每个元素占总时长的 8%）。
• highlight-walk：所有元素从 15% 不透明度开始。聚光灯（带蓝色光晕）按顺序移动经过各个元素，并将经过的元素不透明度提升至 90%。在聚光灯到达每个元素之前，整个图表会以“幽影”效果呈现。
• pulse-flow：所有元素的不透明度均为 100%。边路径采用统一的虚线样式（10px 虚线段 + 6px 间隔），并以固定速度（每个周期 200px）流动，因此所有边的动画速度相同，与长度无关。
• wave：所有元素的不透明度均为 100%。亮度脉冲（1.0→1.4→1.0）伴随蓝色光晕依次扫过各个元素。不改变位置，纯粹呈现视觉波纹效果。

---

常用选项

标志	默认值	说明
-o、--output-dir	与输入相同	生成的 GIF 的输出目录
-s、--style	progressive	动画样式（见上表）
--fps	10	每秒帧数
--duration	4.0	动画时长，单位为秒
--hold	1.0	循环前停留在最后一帧的时长，单位为秒
--theme	default	Mermaid 主题：default、dark、forest、neutral
--bg	#ffffff	背景颜色（十六进制）
--padding	40	图表周围的内边距，单位为像素
--scale	2	渲染缩放比例（2 = Retina 画质）
--custom-css	—	自定义 CSS 文件的路径
--no-loop	—	GIF 仅播放一次，而非循环播放

---

示例

# Dark theme with faster animation
python <skill-root>/scripts/mermaid_to_gif.py arch.mmd --theme dark --bg "#1a1a2e" --duration 3

# High FPS for smoother animation
python <skill-root>/scripts/mermaid_to_gif.py flow.mmd --fps 15 --duration 5

# Batch convert all mermaid blocks from a doc
python <skill-root>/scripts/mermaid_to_gif.py README.md -o ./images/

# Custom CSS for special effects
python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css

# No loop, suitable for one-time playback
python <skill-root>/scripts/mermaid_to_gif.py intro.mmd --no-loop --duration 6

# Lower resolution for smaller file size
python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --scale 1

---

自定义 CSS

创建 CSS 文件，自定义动画期间图表的外观：

/* Rounded nodes with shadow */
.node rect {
    rx: 10;
    filter: drop-shadow(2px 2px 4px rgba(0,0,0,0.3));
}

/* Thicker edge lines */
.edgePath path {
    stroke-width: 2.5;
}

/* Custom background for actors (sequence diagram) */
.actor {
    fill: #e8f4f8;
}

通过 --custom-css 传入：

python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css

---

工作原理

1. 解析输入 — 从 .mmd 或 .md 文件中提取 Mermaid 代码
2. 生成 HTML — 将 Mermaid.js（CDN）和动画 JS/CSS 嵌入独立的 HTML 文件
3. 渲染 — Mermaid.js 通过 Playwright 在无头 Chromium 中将图表渲染为 SVG（使用 2x 设备缩放比例以获得 Retina 画质）
4. 缩放 — 自动将较小的 SVG 放大至最小 700px CSS 宽度，以提高可读性
5. 制作动画 — JS 动画引擎提供 setProgress(t)，用于逐帧控制（t：0→1）。收集元素后，按位置排序（遵循 LR/TB 方向），再按节点与边交错的顺序制作动画
6. 捕获 — Playwright 在每个帧步长截取屏幕截图
7. 组装 — 使用 FFmpeg 两遍调色板编码（palettegen → paletteuse，并采用 Floyd-Steinberg 抖动）

---

重要说明

• 需要互联网：渲染时会从 CDN 加载 Mermaid.js
• 支持的图表类型：流程图、时序图、类图、状态图、ER 图、gitgraph、思维导图、饼图、甘特图等
• 无隐藏元素：所有 4 种样式都会从第 1 帧开始显示图表，无需等待元素出现
• 回退行为：对于无法识别的图表类型，或未检测到可动画元素时，会回退为整个图表的不透明度渐显效果
• 分辨率：默认 scale=2 会生成 Retina 画质的图像（宽约 1400-1600px）。使用 --scale 1 可生成较小的文件
• GIF 大小：对于体积过大的输出，可将 FPS 降至 8、缩短时长、使用 --scale 1，或使用 wave 样式