mdbook-asciinema  

An mdbook preprocessor that embeds asciinema terminal recordings directly into your book pages using the asciinema-player.

Installation

• Install mdbook

• Install mdbook-asciinema:

  To install the latest release published to crates.io:

  cargo install mdbook-asciinema --locked

  To install the latest version committed to GitHub:

  cargo install mdbook-asciinema --git https://github.com/github/mdbook-asciinema.git --locked

Getting Started

Create a new book.

mdbook init --force --title <TITLE>

Edit the book.toml file; add the asciinema preprocessor.

[book]
title = "My Book"

[preprocessor.asciinema]

Add your asciicast file/s into a path underneath src.

PROJ_DIR
├── book
├── book.toml
└── src
    ├── chapter_1.md
    ├── SUMMARY.md
    └── video
        └── demo.cast

Add a helper tag to a markdown file (e.g. chapter_1.md).

# Chapter 1

{{ #asciinema video/demo.cast }}

See the example directory for a ready-to-run setup.

Preview the book by running mdbook serve.

> mdbook serve
 INFO Book building has started
 INFO mdbook_asciinema: created "[PROJ_DIR]/src/lib/asciinema-player/asciinema-player.min.js"
 INFO mdbook_asciinema: created "[PROJ_DIR]/src/lib/asciinema-player/asciinema-player.css"
 INFO Running the html backend
 INFO HTML book written to `[PROJ_DIR]/book`
 INFO Serving on: http://localhost:3000
 INFO Watching for changes...

Syntax

The general form of the helper tag is:

{{ #asciinema <path> [opts=<path>] [scope=<string>] }}

Parameter	Required	Description
path	Yes	Relative path (from src) to a .cast asciicast file.
opts	No	Relative path to a JSON file containing player options.
scope	No	Scope identifer to provide control of a specific asciinema player. The provided value should be an alphanumeric string of length between 5 and 10 characters. If this value is not provided or does not meet these restrictions, a random alphanumeric string 10 characters in length will be generated. Each asciinema player will be declared: const player_{scope} = AsciinemaPlayer.create('{path}', document.querySelector('div[b-{scope}]'));.

Player Options

To customise playback, create a JSON file with asciinema-player options and reference it with the opts parameter:

{
  "autoPlay": true,
  "speed": 2,
  "idleTimeLimit": 0.5,
  "cols": 400,
  "rows": 51,
  "fit": false,
  "terminalFontSize": "15px"
}

{{ #asciinema video/demo.cast opts=video/player-opts.json }}

Escaping

To display the helper tag literally without rendering it, prefix it with a backslash:

\{{ #asciinema video/demo.cast }}

How It Works

When mdbook builds or serves the book, this preprocessor:

1. Copies the bundled asciinema-player JavaScript and CSS assets into src/lib/asciinema-player/.
2. Scans each chapter for {{ #asciinema ... }} tags.
3. Replaces each tag with the HTML and JavaScript needed to render an embedded asciinema-player.

Verifying Release Artifacts

All release binaries include build provenance attestations and an SBOM (Software Bill of Materials) in SPDX format.

To verify the provenance of a downloaded binary:

gh attestation verify <artifact-file> --repo github/mdbook-asciinema

To verify the SBOM attestation:

gh attestation verify <artifact-file> --repo github/mdbook-asciinema --predicate-type https://spdx.dev/Document

License

Licensed under the MIT license.