mermaid-to-gif

Turns Mermaid diagrams into animated GIFs, working from standalone .mmd files or by extracting fenced mermaid code blocks out of Markdown documents. It is aimed at producing animated visuals for presentations, documentation, or social media, and can batch-convert every diagram in a document, emitting one GIF per block. FFmpeg, Python 3.8 or newer, and Playwright (with a Chromium install) are required.

Four animation styles are offered, each keeping the full diagram visible from the first frame while adding motion: progressive (the default) activates dimmed elements sequentially and draws edges in; highlight-walk moves a glowing spotlight through each element for step-by-step processes; pulse-flow turns edges into uniformly flowing dashed lines to convey data movement; and wave sweeps a brightness ripple across elements for simple overviews. A context-aware selection guide encourages reading the Markdown text around each diagram and matching style to meaning, using pulse-flow for pipelines and request paths, progressive for architecture layers and sequence messages, highlight-walk for tutorials, and wave for decorative or reference diagrams, rather than applying one style everywhere.

The script is driven from the command line with the input file (or files) and an output directory. A range of options tune the result: style, fps, duration, hold time before looping, Mermaid theme (default, dark, forest, neutral), background color, padding, render scale for retina quality, a custom CSS file, and a no-loop flag for single playback. Custom CSS can restyle nodes, edges, and sequence-diagram actors during the animation. Internally it extracts the Mermaid code, generates a self-contained HTML file embedding Mermaid.js plus animation JS and CSS, and renders frames. After generating GIFs, the original mermaid blocks can be replaced with image references using descriptive alt text and relative paths.