SKILL.md
唯讀
名稱
mermaid-to-gif
描述
將 .mmd 或 .md 檔案中的 Mermaid 程式碼區塊轉換為動畫 GIF，支援多種動畫樣式（漸進、高亮走訪、脈衝流動、波浪）。
技能：Mermaid 轉 GIF
將 Mermaid 圖表轉換為具有豐富動畫效果的動畫 GIF。支援 .mmd 檔案以及從 .md 檔案中提取 ```mermaid 程式碼區塊。
前置需求：FFmpeg、Python 3.8+、Playwright（
pip install playwright && playwright install chromium）
使用時機
- 使用者想要將 Mermaid 圖表轉換為動畫 GIF
- 使用者有
.mmd檔案或包含 mermaid 程式碼區塊的.md檔案 - 使用者需要為簡報、文件或社群媒體製作動畫視覺效果
- 使用者想要批次轉換文件中的所有 mermaid 區塊
情境感知的樣式選擇
重要：從 .md 檔案轉換 mermaid 區塊時，請閱讀周圍的 markdown 上下文，為每個圖表選擇最合適的動畫樣式。不要盲目對所有區塊套用相同樣式。
決策指南
- 閱讀每個 mermaid 區塊周圍的 markdown 文字 — 了解圖表在說明什麼
- 將樣式與語義含義匹配：
| 上下文線索 | 建議樣式 | 理由 |
|---|---|---|
| 資料管線、ETL 流程、請求/回應路徑 | pulse-flow |
流動的虛線傳達資料移動 |
| 架構層級、組織圖、階層結構 | progressive |
元素逐層啟動 |
| 逐步流程、教學引導 | highlight-walk |
聚光燈引導讀者逐步進行 |
| 系統概覽、標題圖表、簡單參考 | wave |
亮度漣漪增加活力而不分散注意力 |
| 包含訊息流程的序列圖 | progressive |
訊息按對話順序逐一啟動 |
| 類別/ER 圖（參考/靜態） | progressive 或 wave |
結構亮起或獲得微妙的漣漪 |
-
考慮特殊處理：
- 如果周圍文字提到「資料從 A 流向 B」，即使流程圖很簡單，也使用
pulse-flow - 如果文字描述「三層」或「兩層」，使用
progressive逐層啟動 - 如果圖表是裝飾性或補充性的，使用
wave保持簡單 - 對於非常大或複雜的圖表，偏好使用
wave或較短的--duration以保持 GIF 大小合理
- 如果周圍文字提到「資料從 A 流向 B」，即使流程圖很簡單，也使用
-
每個區塊的樣式覆蓋：批次處理
.md檔案時，可能需要多次執行腳本並使用不同樣式來提取特定區塊。或者使用合理的預設值處理整個檔案，然後對需要不同處理的個別區塊重新執行。
範例：情境感知處理
## 資料攝取管線 ← 上下文：「管線」→ pulse-flow
[mermaid 區塊：包含 ETL 階段的 graph LR]
## 系統架構 ← 上下文：「架構」→ progressive
[mermaid 區塊：包含層級的 graph TD]
## 快速參考 ← 上下文：「參考」→ wave
[mermaid 區塊：簡單圖表]
預設工作流程
單一 .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 程式碼區塊取代為圖片參考：
根據圖表內容使用描述性的替代文字。圖片路徑應相對於 markdown 檔案。
動畫樣式
所有樣式都讓圖表從第一幀開始完全可見 — 沒有元素從隱藏開始或從零淡入。每個樣式在加入動畫的同時，使用者始終能看到完整的圖表結構。
| 樣式 | 效果 | 最佳用途 |
|---|---|---|
progressive（預設） |
所有元素從暗淡（25% 不透明度）開始，依序啟動至全亮；邊線以描邊動畫繪製 | 流程圖、架構圖、階層圖 |
highlight-walk |
所有元素從暗淡（15%）開始；帶有藍色光暈的聚光燈依序移動到每個元素，已訪問的元素保持明亮 | 逐步流程、教學 |
pulse-flow |
所有元素完全可見；邊線變成流動的虛線（統一的虛線大小和速度） | 資料流、管線、請求路徑 |
wave |
所有元素完全可見；亮度脈衝 + 藍色光暈漣漪依序掃過元素 | 簡單圖表、概覽、參考 |
動畫細節
- progressive：元素從 25% 不透明度開始（圖表結構始終可見）。節點、邊線和標籤以交錯順序啟動（節點 → 邊線 → 節點 → 邊線），遵循流向。邊線使用 stroke-dashoffset 以視覺方式繪製。啟動速度很快（每個元素佔總持續時間的 8%）。
- highlight-walk：所有元素從 15% 不透明度開始。聚光燈（帶藍色光暈）依序移動到元素，已訪問的元素保持 90% 不透明度。在聚光燈到達每個元素之前，整個圖表以「鬼影」形式可見。
- pulse-flow：所有元素保持全不透明度。邊線路徑獲得統一的虛線模式（10px 虛線 + 6px 間距），以固定速度（200px/週期）流動，因此所有邊線無論長度如何都以相同速度動畫。
- wave：所有元素保持全不透明度。亮度脈衝（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，不循環 |
範例
# 深色主題搭配較快動畫
python <skill-root>/scripts/mermaid_to_gif.py arch.mmd --theme dark --bg "#1a1a2e" --duration 3
# 高 FPS 以獲得流暢動畫
python <skill-root>/scripts/mermaid_to_gif.py flow.mmd --fps 15 --duration 5
# 批次轉換文件中的所有 mermaid 區塊
python <skill-root>/scripts/mermaid_to_gif.py README.md -o ./images/
# 自訂 CSS 以獲得特殊效果
python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css
# 不循環，適合一次性播放
python <skill-root>/scripts/mermaid_to_gif.py intro.mmd --no-loop --duration 6
# 較低解析度以減小檔案大小
python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --scale 1
自訂 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 傳入：
python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css
運作原理
- 解析輸入 — 從
.mmd或.md檔案中提取 Mermaid 程式碼 - 產生 HTML — 將 Mermaid.js（CDN）+ 動畫 JS/CSS 嵌入到自包含的 HTML 檔案中
- 渲染 — Mermaid.js 透過 Playwright 在無頭 Chromium 中將圖表渲染為 SVG（使用 2 倍裝置縮放以獲得 Retina 品質）
- 縮放 — 小型 SVG 會自動放大到最小 700px CSS 寬度以確保可讀性
- 動畫 — JS 動畫引擎暴露
setProgress(t)以逐幀控制（t：0→1）。元素被收集、按位置排序（尊重 LR/TB 方向），並以交錯的節點-邊線順序動畫 - 捕捉 — Playwright 在每個幀步驟拍攝螢幕截圖
- 組合 — FFmpeg 兩階段調色板編碼（palettegen → paletteuse 搭配 Floyd-Steinberg 抖色）
重要注意事項
- 需要網路：Mermaid.js 在渲染時從 CDN 載入
- 支援的圖表類型：流程圖、序列圖、類別圖、狀態圖、ER 圖、Git 圖、心智圖、圓餅圖、甘特圖等
- 無隱藏元素：所有 4 種樣式都讓圖表從第一幀開始可見 — 無需等待元素出現
- 備援行為：對於無法識別的圖表類型或未偵測到可動畫元素時，會回退為整個圖表的不透明度顯現
- 解析度：預設 scale=2 可產生 Retina 品質的圖片（約 1400-1600px 寬）。使用
--scale 1可獲得較小檔案 - GIF 大小：對於非常大的輸出，請將 FPS 降低至 8、縮短持續時間、使用
--scale 1，或使用wave樣式
