Skip to content
mermaid-to-gif logo

Skill: Mermaid to GIF

mermaid-to-gif

Convert Mermaid code blocks in .mmd or .md files to animated GIFs with customizable animation styles (progressive, highlight walk, pulse flow, wave).

SKILL.md

Full skill instructions

Skill: Mermaid to 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)


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

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.

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:
Context ClueRecommended StyleReasoning
Data pipeline, ETL flow, request/​response pathpulse-flowFlowing dashed lines convey data movement
Architecture layers, org chart, hierarchyprogressiveElements activate layer-by-layer
Step-by-step process, tutorial walkthroughhighlight-walkSpotlight guides the reader through each step
System overview, title diagram, simple referencewaveBrightness ripple adds life without distraction
Sequence diagram with message flowprogressiveMessages activate one by one in conversation order
Class/​ER diagram (reference/​static)progressive or waveStructure lights up or gets a subtle ripple
  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 <skill-root>/​scripts/​mermaid_to_gif.py diagram.mmd

Markdown file with mermaid blocks

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

This extracts all ```mermaid code blocks and generates one GIF per block.

Multiple files

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/

Replacing mermaid blocks in markdown

After generating GIFs, replace the original ```mermaid code blocks with image references:

![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.


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.

StyleEffectBest For
progressive (default)All elements start dimmed (25% opacity), activate sequentially to full brightness; edges draw in with stroke animationFlowcharts, architecture, hierarchy
highlight-walkAll elements start dimmed (15%); a spotlight with blue glow moves through each element, leaving visited ones brightStep-by-step process, tutorials
pulse-flowAll elements fully visible; edges become flowing dashed lines (uniform dash size and speed)Data flow, pipelines, request paths
waveAll elements fully visible; a brightness pulse + blue glow ripple sweeps through elements sequentiallySimple diagrams, overviews, reference

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

FlagDefaultDescription
-o, --output-dirSame as inputOutput directory for generated GIFs
-s, --styleprogressiveAnimation style (see table above)
--fps10Frames per second
--duration4.0Animation duration in seconds
--hold1.0Hold last frame before looping (seconds)
--themedefaultMermaid theme: default, dark, forest, neutral
--bg#ffffffBackground color (hex)
--padding40Padding around diagram in pixels
--scale2Render scale factor (2 = retina quality)
--custom-css—Path to custom CSS file
--no-loop—Play GIF once instead of looping

Examples

# 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

Custom CSS

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

/​* 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:

python <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

More Marketing & SEO skills

copywriting logo
Marketing & SEO

copywriting

Marketing copy for homepages, landing pages, pricing pages, and other conversion-focused web pages.

53.3K 216.1K
View
flux-2-klein logo
Marketing & SEO

flux-2-klein

Fast image generation with Flux 2 Klein, optimized for sub-second iteration and multi-reference brand styling.

52 176.2K
View
marketing-psychology logo
Marketing & SEO

marketing-psychology

Psychological principles and mental models for understanding customer behavior and influencing marketing decisions.

53.3K 153K
View
content-strategy logo
Marketing & SEO

content-strategy

Plan searchable and shareable content that drives traffic, builds authority, and generates leads.

53.3K 150.9K
View
programmatic-seo logo
Marketing & SEO

programmatic-seo

Build SEO-optimized pages at scale using templates, data, and proven playbook patterns.

53.3K 140.1K
View
marketing-ideas logo
Marketing & SEO

marketing-ideas

Brainstorm and prioritize marketing strategies tailored to your SaaS stage, budget, and goals.

53.3K 137.2K
View
ai-seo logo
Marketing & SEO

ai-seo

Optimize content for discovery, citation, and visibility across AI search platforms and LLM assistants.

53.3K 136.7K
View
copy-editing logo
Marketing & SEO

copy-editing

Systematic improvement of existing marketing copy through seven focused editing passes.

53.3K 136.4K
View
site-architecture logo
Marketing & SEO

site-architecture

Plan and optimize your website's page hierarchy, navigation, URL structure, and internal linking.

53.3K 112.8K
View
revops logo
Marketing & SEO

revops

Design and optimize systems connecting marketing, sales, and customer success into a unified revenue engine.

53.3K 104.9K
View
brand-guidelines logo
Marketing & SEO

brand-guidelines

Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.

179.7K 100.1K
View
website-to-hyperframes logo
Marketing & SEO

website-to-hyperframes

Convert websites into professional HyperFrames videos with guided storyboarding and brand-aligned composition.

57K 93.5K
View

Sales & marketing AI tools

KreadoAI logo
Sales & marketing

KreadoAI

Revolutionize Video Creation with AI-Generated Avatars and Voices

Paid
View
Followr logo
Sales & marketing

Followr

Social media on autopilot

Paid
View
Logodiffusion logo
Sales & marketing

Logodiffusion

Design custom logos instantly with AI.

Paid
View
I
Sales & marketing

Ideogram

Text-heavy marketing and design images

Freemium
View
Prompt Silo logo
Sales & marketing

Prompt Silo

Boost Your SEO with Content and SEO Silos

Free
View
Marketing Blocks logo
Sales & marketing

Marketing Blocks

Revolutionize Your Marketing with AI-Powered MarketingBlocks!

Paid
View
Scrip AI logo
Sales & marketing

Scrip AI

10X faster & free AI content creation for 100+ use cases

Free
View
Tribescaler logo
Sales & marketing

Tribescaler

Tribescaler | Make Your Tweets Go Viral

Paid
View