Skip to content
Munim · OSS

readmecast

Turn a Markdown file into a gorgeous, self-contained animated terminal demo SVG. No hand-authored tape files, no recording session, no runtime player.

readmecast reads the shell snippets you already wrote in your README, and renders an animated terminal that “types” each command character-by-character, pauses, then reveals its output line by line. The result is a single standalone SVG with pure-CSS @keyframes animation — so it animates even when embedded as a plain <img>, which is exactly how GitHub renders README images. No GIF bloat, no external player, no JavaScript.

Terminal window
$ npm install readmecast
added 1 package in 1.2s
$ readmecast README.md -o demo.svg
wrote demo.svg
$ echo "embed it in your README and ship"
embed it in your README and ship

That fenced block above is exactly the kind of input readmecast consumes. Point the CLI at the file, and it casts those three commands and their output into one animated demo.svg you drop straight into your README:

![demo](demo.svg)

Your docs are the source of truth

Write the session once, in normal fenced code blocks, and let readmecast cast it. There are no .tape or .cast files to keep in sync with reality.

Animates on GitHub

GitHub strips <script> from SVGs but keeps CSS animations. A single <img src="demo.svg"> plays the typing and reveal — no GIF, no external asset.

Self-contained & safe

Pure CSS animation, no JavaScript. Commands are never executed — the SVG renders exactly the output you documented, so it can’t surprise you.

Dependency-light

A hand-rolled Markdown line scanner and a string-built SVG. No Markdown parser, no headless browser, no native binaries.

How it works

Section titled “How it works”
  1. Extract. readmecast scans your Markdown for fenced shell blocks (bash, sh, shell, console, zsh, shell-session). Inside each, lines beginning with $ or > are commands; the lines after a command — up to the next command — are its output.
  2. Render. Each step becomes a row in a terminal window. Commands type out character-by-character behind an animated clip rect with a blinking cursor; output lines snap into view a beat later.
  3. Embed. The whole demo is encoded as staggered CSS @keyframes with animation-delay, so the SVG is fully self-contained and plays inside an <img> tag.

Next steps

Section titled “Next steps”
Quick start From install to an animated SVG embedded in your README, in a few steps.
Markdown format Exactly which blocks, prompts, and lines become commands and output.
CLI Every flag — themes, width, speed, titles, looping, and stdin.
Programmatic API parseMarkdown, renderSvg, markdownToSvg, and the exported types.

MIT   github.com/abdulmunimjemal/readmecast