mermaid-to-gif

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Mermaid to GIF

技能：Mermaid转GIF

Convert Mermaid diagrams into animated GIFs with rich animation effects. Supports

.mmd

files and extracting

```mermaid

code blocks from

.md

files.

Prerequisites: FFmpeg, Python 3.8+, Playwright (
pip install playwright && playwright install chromium
)

将Mermaid图表转换为具有丰富动画效果的动画GIF。支持.mmd文件以及从.md文件中提取

mermaid

代码块。

前置要求：FFmpeg、Python 3.8+、Playwright（执行
pip install playwright && playwright install chromium
安装）

When to Use

适用场景

The user wants to convert Mermaid diagrams to animated GIFs
The user has
```
.mmd
```
files or
```
.md
```
files containing mermaid code blocks
The user needs animated visuals for presentations, documentation, or social media
The user wants to batch-convert all mermaid blocks in a document

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

Context-Aware Style Selection

上下文感知的样式选择

IMPORTANT: When converting mermaid blocks from

.md

files, read the surrounding markdown context to choose the most appropriate animation style for each diagram. Do NOT blindly apply the same style to all blocks.

重要提示：从.md文件转换Mermaid代码块时，需读取周围的Markdown上下文，为每个图表选择最合适的动画样式。切勿盲目对所有代码块应用相同样式。

Decision Guide

决策指南

Read the markdown text around each mermaid block — understand what the diagram is illustrating
Match the style to the semantic meaning:

Context Clue	Recommended Style	Reasoning
Data pipeline, ETL flow, request/response path	`pulse-flow`	Flowing dashed lines convey data movement
Architecture layers, org chart, hierarchy	`progressive`	Elements activate layer-by-layer
Step-by-step process, tutorial walkthrough	`highlight-walk`	Spotlight guides the reader through each step
System overview, title diagram, simple reference	`wave`	Brightness ripple adds life without distraction
Sequence diagram with message flow	`progressive`	Messages activate one by one in conversation order
Class/ER diagram (reference/static)	`progressive` or `wave`	Structure lights up or gets a subtle ripple

Consider special handling:
- If the surrounding text says "data flows from A to B", use
```
pulse-flow
```
  even for a simple flowchart
- If the text describes "three layers" or "two tiers", use
```
progressive
```
  to activate layer-by-layer
- If the diagram is decorative or supplementary, use
```
wave
```
  to keep it simple
- For very large or complex diagrams, prefer
```
wave
```
  or shorter
```
--duration
```
  to keep GIF size reasonable
Per-block style override: When batch-processing a
```
.md
```
file, you may need to run the script multiple times with different styles, extracting specific blocks. Or process the whole file with a sensible default and re-run individual blocks that need different treatment.

读取每个Mermaid代码块周围的Markdown文本——理解图表所展示的内容
根据语义匹配样式：

上下文线索	推荐样式	理由
数据管道、ETL流程、请求/响应路径	`pulse-flow`	流动的虚线能传达数据移动的效果
架构分层、组织结构图、层级关系	`progressive`	元素逐层激活展示
分步流程、教程演练	`highlight-walk`	聚光灯引导读者逐步浏览每个步骤
系统概览、标题图表、简单参考图	`wave`	亮度波纹效果为图表增添活力又不会分散注意力
带有消息流的序列图	`progressive`	消息按照对话顺序逐个激活
类图/ER图（参考/静态）	`progressive` 或 `wave`	结构逐步点亮或呈现微妙波纹效果

特殊处理情况：
- 如果周围文本提到“数据从A流向B”，即使是简单流程图也使用
```
pulse-flow
```
  样式
- 如果文本描述“三层架构”或“两层结构”，使用
```
progressive
```
  样式逐层激活
- 如果图表是装饰性或补充性内容，使用
```
wave
```
  样式保持简洁
- 对于非常大或复杂的图表，优先选择
```
wave
```
  样式或缩短
```
--duration
```
  参数以控制GIF文件大小
单块样式覆盖：批量处理.md文件时，可能需要多次运行脚本并使用不同样式来提取特定代码块。或者先使用合理的默认值处理整个文件，再重新处理需要不同样式的单个代码块。

Example: Context-Aware Processing

示例：上下文感知处理

markdown

undefined

markdown

undefined

Data Ingestion Pipeline ← context: "pipeline" → pulse-flow

数据摄入管道 ← 上下文：“管道” → 使用pulse-flow

[mermaid block: graph LR with ETL stages]

[mermaid代码块：包含ETL阶段的graph LR图表]

System Architecture ← context: "architecture" → progressive

系统架构 ← 上下文：“架构” → 使用progressive

[mermaid block: graph TD with layers]

[mermaid代码块：包含分层结构的graph TD图表]

Quick Reference ← context: "reference" → wave

快速参考 ← 上下文：“参考” → 使用wave

[mermaid block: simple diagram]

---

[mermaid代码块：简单图表]

---

Default Workflow

默认工作流程

Single .mmd file

单个.mmd文件

bash

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py diagram.mmd

bash

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py diagram.mmd

Markdown file with mermaid blocks

包含Mermaid代码块的Markdown文件

bash

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py document.md -o ./images/

This extracts all

```mermaid

code blocks and generates one GIF per block.

bash

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py document.md -o ./images/

此命令会提取所有

mermaid

代码块，并为每个代码块生成一个GIF文件。

Multiple files

多个文件

bash

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py *.mmd -o ./gifs/
python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py doc1.md doc2.md -o ./gifs/

bash

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py *.mmd -o ./gifs/
python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py doc1.md doc2.md -o ./gifs/

Replacing mermaid blocks in markdown

替换Markdown中的Mermaid代码块

After generating GIFs, replace the original

```mermaid

code blocks with image references:

markdown

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

Use descriptive alt text based on the diagram content. The image path should be relative to the markdown file.

生成GIF后，将原始的

mermaid

代码块替换为图片引用：

markdown

![流程图](images/document-1.gif)

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

Animation Styles

动画样式

All styles keep the diagram fully visible from frame 1 — no elements start hidden or fade in from zero. Every style adds motion while the user can see the complete diagram structure at all times.

Style	Effect	Best For
`progressive` (default)	All elements start dimmed (25% opacity), activate sequentially to full brightness; edges draw in with stroke animation	Flowcharts, architecture, hierarchy
`highlight-walk`	All elements start dimmed (15%); a spotlight with blue glow moves through each element, leaving visited ones bright	Step-by-step process, tutorials
`pulse-flow`	All elements fully visible; edges become flowing dashed lines (uniform dash size and speed)	Data flow, pipelines, request paths
`wave`	All elements fully visible; a brightness pulse + blue glow ripple sweeps through elements sequentially	Simple diagrams, overviews, reference

所有样式都保持图表从第一帧开始完全可见——没有元素会从隐藏状态开始或从完全透明淡入。每种样式在添加动态效果的同时，用户始终能看到完整的图表结构。

样式	效果	最佳适用场景
`progressive` （默认）	所有元素初始为半透明（25%不透明度），按顺序激活至完全亮度；边缘通过描边动画绘制出来	流程图、架构图、层级图
`highlight-walk`	所有元素初始为低透明度（15%）；带有蓝色光晕的聚光灯按顺序移动到每个元素，已访问的元素保持高亮	分步流程、教程
`pulse-flow`	所有元素保持完全不透明度；边缘变为流动的虚线（统一的虚线尺寸和速度）	数据流、管道、请求路径
`wave`	所有元素保持完全不透明度；带有蓝色光晕的亮度脉冲按顺序扫过所有元素	简单图表、概览图、参考图

Animation Details

动画细节

progressive: Elements start at 25% opacity (diagram structure always visible). Nodes, edges, and labels activate in interleaved order (node → edge → node → edge) following flow direction. Edges use stroke-dashoffset to draw in visually. Activation is fast (8% of total duration per element).
highlight-walk: All elements start at 15% opacity. A spotlight (with blue glow) moves through elements in order, leaving visited elements at 90% opacity. The whole diagram is visible as a "ghost" before the spotlight reaches each element.
pulse-flow: All elements at full opacity. Edge paths get a uniform dashed pattern (10px dash + 6px gap) that flows at a fixed speed (200px/cycle), so all edges animate at the same pace regardless of length.
wave: All elements at full opacity. A brightness pulse (1.0→1.4→1.0) with blue glow sweeps through elements sequentially. No position changes — purely a visual ripple effect.

progressive：元素初始不透明度为25%（图表结构始终可见）。节点、边缘和标签按照流动方向以交错顺序（节点→边缘→节点→边缘）激活。边缘使用stroke-dashoffset实现描边动画。激活速度较快（每个元素占用总时长的8%）。
highlight-walk：所有元素初始不透明度为15%。带有蓝色光晕的聚光灯按顺序移动到每个元素，已访问的元素保持90%不透明度。在聚光灯到达每个元素之前，整个图表以“虚影”状态可见。
pulse-flow：所有元素保持完全不透明度。边缘路径应用统一的虚线样式（10px虚线+6px间隔），并以固定速度（200px/周期）流动，因此无论边缘长度如何，所有边缘的动画速度一致。
wave：所有元素保持完全不透明度。带有蓝色光晕的亮度脉冲（1.0→1.4→1.0）按顺序扫过所有元素。无位置变化——仅为视觉波纹效果。

Common Options

常用选项

Flag	Default	Description
`-o` , `--output-dir`	Same as input	Output directory for generated GIFs
`-s` , `--style`	`progressive`	Animation style (see table above)
`--fps`	`10`	Frames per second
`--duration`	`4.0`	Animation duration in seconds
`--hold`	`1.0`	Hold last frame before looping (seconds)
`--theme`	`default`	Mermaid theme: default, dark, forest, neutral
`--bg`	`#ffffff`	Background color (hex)
`--padding`	`40`	Padding around diagram in pixels
`--scale`	`2`	Render scale factor (2 = retina quality)
`--custom-css`	—	Path to custom CSS file
`--no-loop`	—	Play GIF once instead of looping

参数	默认值	描述
`-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=视网膜质量）
`--custom-css`	—	自定义CSS文件路径
`--no-loop`	—	GIF仅播放一次而非循环播放

Examples

示例

bash

undefined

bash

undefined

Dark theme with faster animation

深色主题+更快的动画

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py arch.mmd --theme dark --bg "#1a1a2e" --duration 3

High FPS for smoother animation

更高FPS实现更流畅的动画

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py flow.mmd --fps 15 --duration 5

Batch convert all mermaid blocks from a doc

批量转换文档中的所有Mermaid代码块

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py README.md -o ./images/

Custom CSS for special effects

使用自定义CSS实现特殊效果

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css

No loop, suitable for one-time playback

不循环播放，适用于一次性展示

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py intro.mmd --no-loop --duration 6

Lower resolution for smaller file size

更低分辨率以减小文件大小

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py diagram.mmd --scale 1

---

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py diagram.mmd --scale 1

---

Custom CSS

自定义CSS

Create a CSS file to customize the appearance of the diagram during animation:

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;
}

Pass it via

--custom-css

bash

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css

创建CSS文件来自定义动画过程中图表的外观：

css

/* 带阴影的圆角节点 */
.node rect {
    rx: 10;
    filter: drop-shadow(2px 2px 4px rgba(0,0,0,0.3));
}

/* 更粗的边缘线条 */
.edgePath path {
    stroke-width: 2.5;
}

/* 为参与者自定义背景（序列图） */
.actor {
    fill: #e8f4f8;
}

通过

--custom-css

参数传入：

bash

python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css

How It Works

工作原理

Parse input — extract Mermaid code from
```
.mmd
```
or
```
.md
```
files
Generate HTML — embed Mermaid.js (CDN) + animation JS/CSS in a self-contained HTML file
Render — Mermaid.js renders the diagram to SVG in headless Chromium via Playwright (with 2x device scale for retina quality)
Scale — small SVGs are automatically scaled up to minimum 700px CSS width for readability
Animate — JS animation engine exposes
```
setProgress(t)
```
for frame-by-frame control (t: 0→1). Elements are collected, sorted by position (respecting LR/TB direction), and animated in interleaved node-edge order
Capture — Playwright takes a screenshot at each frame step
Assemble — FFmpeg two-pass palette encoding (palettegen → paletteuse with Floyd-Steinberg dithering)

解析输入——从.mmd或.md文件中提取Mermaid代码
生成HTML——将Mermaid.js（CDN加载）+动画JS/CSS嵌入到独立的HTML文件中
渲染——Mermaid.js通过Playwright在无头Chromium中将图表渲染为SVG（使用2倍设备缩放因子实现视网膜质量）
缩放——小尺寸SVG会自动放大到最小700px的CSS宽度以保证可读性
动画——JS动画引擎暴露
```
setProgress(t)
```
接口用于逐帧控制（t: 0→1）。元素会被收集并按位置排序（尊重LR/TB方向），然后以节点-边缘交错的顺序进行动画
捕获——Playwright在每个帧步骤中截取屏幕截图
合成——FFmpeg通过两次编码生成调色板（palettegen → paletteuse结合Floyd-Steinberg抖动算法）

Important Notes

重要说明

Internet required: Mermaid.js is loaded from CDN at render time
Supported diagram types: flowchart, sequence, class, state, ER, gitgraph, mindmap, pie, gantt, and more
No hidden elements: all 4 styles keep the diagram visible from frame 1 — no waiting for elements to appear
Fallback behavior: for unrecognized diagram types or when no animatable elements are detected, falls back to a whole-diagram opacity reveal
Resolution: default scale=2 produces retina-quality images (~1400-1600px wide). Use
```
--scale 1
```
for smaller files
GIF size: for very large outputs, reduce FPS to 8, shorten duration, use
```
--scale 1
```
, or use
```
wave
```
style

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