Skill: Mermaid to GIF

.mmd

```mermaid

.md

Prerequisites: 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

Context-Aware Style Selection

.md

Decision Guide

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

pulse-flow

progressive

highlight-walk

wave

progressive

progressive

wave

1. 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
2. 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.

Example: Context-Aware Processing

## 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]

Default Workflow

Single .mmd file

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

Markdown file with mermaid blocks

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

```mermaid

Multiple files

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

```mermaid

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

Animation Styles

progressive

highlight-walk

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.

Common Options

-o

--output-dir

-s

--style

progressive

--fps

10

--duration

4.0

--hold

1.0

--theme

default

--bg

#ffffff

--padding

40

--scale

2

--custom-css

--no-loop

Examples

# 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
python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py flow.mmd --fps 15 --duration 5

# Batch convert all mermaid blocks from a doc
python ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py README.md -o ./images/

# Custom CSS for special effects
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

Custom 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 ${CLAUDE_SKILL_ROOT}/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css

How It Works

1. Parse input — extract Mermaid code from

   .mmd

   or

   .md

   files
2. Generate HTML — embed Mermaid.js (CDN) + animation JS/CSS in a self-contained HTML file
3. Render — Mermaid.js renders the diagram to SVG in headless Chromium via Playwright (with 2x device scale for retina quality)
4. Scale — small SVGs are automatically scaled up to minimum 700px CSS width for readability
5. 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
6. Capture — Playwright takes a screenshot at each frame step
7. Assemble — FFmpeg two-pass palette encoding (palettegen → paletteuse with Floyd-Steinberg dithering)

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