readmecast

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

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 output 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.

The SVG above is the real output of readmecast examples/demo.md. On GitHub it animates.

Why

• Your docs are the source of truth. Write the session once, in fenced code blocks, and let readmecast cast it. No .tape / cast files to keep in sync.
• Animates on GitHub. Animated SVGs embedded with ![](demo.svg) / <img src="demo.svg"> do animate on GitHub. No GIF bloat, no external player.
• Self-contained & safe. Pure CSS animation (no JavaScript). Commands are not executed — the output rendered is exactly the output you documented.
• Dependency-light. Hand-rolled Markdown extraction and string-built SVG. No Markdown parser, no headless browser.

Install

npm install -g readmecast
# or run once, no install:
npx readmecast README.md -o demo.svg

Usage

Write your session in a fenced shell block (```bash, ```sh, ```shell, or ```console). Lines beginning with $ (or > ) are commands; the lines after a command, up to the next command, are its output:

```bash
$ npm install readmecast
added 1 package in 1.2s
$ readmecast README.md -o demo.svg
wrote demo.svg
```

Then cast it:

readmecast README.md -o demo.svg          # write an SVG
cat README.md | readmecast > demo.svg     # or pipe on stdin
readmecast README.md --theme light --title "my-cli" -o demo.svg

Embed the result in your README:

![demo](demo.svg)

Options

| Option | Description | Default | | --- | --- | --- | | -o, --out <file> | Write the SVG here. Omit to write to stdout. | stdout | | --theme <name> | Color theme: dark or light. | dark | | --width <cols> | Terminal width in columns. | 80 | | --speed <secs> | Typing speed in seconds per character. | 0.06 | | --title <text> | Window title shown in the title bar. | none | | --no-loop | Play the animation once instead of looping. | loops | | -h, --help | Show help. | | | -v, --version | Show version. | |

Programmatic API

readmecast is also a library. Both functions are pure (no I/O, no execution):

import { parseMarkdown, renderSvg, markdownToSvg } from "readmecast";

const steps = parseMarkdown("```bash\n$ echo hi\nhi\n```");
// → [{ command: "echo hi", output: "hi" }]

const svg = renderSvg(steps, { theme: "dark", title: "demo" });

// or in one shot:
const svg2 = markdownToSvg(myMarkdown, { theme: "light" });

How animation works on GitHub

GitHub strips <script> from SVGs but keeps CSS animations. readmecast encodes the whole demo as staggered @keyframes with animation-delay, so a single <img src="demo.svg"> plays the typing and reveal with no JavaScript and no external assets. That is why the SVG is the right format here — a GIF would be larger and lower quality, and an asciinema player needs JS that READMEs can't run.

Roadmap

• --run: optionally execute the commands and capture live output (opt-in, off by default).

License

MIT © 2026 Abdulmunim Jemal