For a while now, I’ve wanted some way to include richer terminal output in blog posts; I’d like to present longer chunks of output without interfering with the rest of the text, and ideally preserve colours. There’s probably some fairly simple HTML/CSS option to encapsulate the long text in to a smaller view, however the colour preservation seems like it would be pretty hard with my existing blog workflow. Screen recording is one possibility that could satisfy both goals, but typical video formats don’t compress text very well so there would be a tradeoff between file size (and thereby bandwidth that I might have to pay for) and legibility so I haven’t pursued screen recording.

Yesterday, I started a blog post about [fixing a bug] which would be nicely illustrated by something like a terminal video, so I looked around a little and found asciinema which is a really neat option!

Recording terminal output with asciinema output is pretty easy, and so far it hasn’t taken too much effort to get the basics of the web player integrated in to this blog, to enable content like this:

The above was recorded using a rather long command:

asciinema rec --tty-size
120x24 --overwrite -c "DEFMT_LOG=debug cargo embed --example=blinky_basic
--features=usb" ~/Projects/blog/media/20250404-demo.cast

…but it’ll be easy enough to wrap up the relevant bits in to a shell script/alias. Or, I understand wezterm supports recording asciicast natively; maybe it’s time to try switching away from Alacritty.

To date, the changes to my blog have been absolutely minimal - really just cribbing from the player docs, but there are a number of things to sort out:

• Only include the asciinema CSS and JS when a post will use it
• Set up deferred loading of the player JS, and perhaps there’s some way to have the browser download the asciicast file upfront too?
• Create a Jekyll macro (or whatever it’s called) to make it easier to integrate asciinema recordings in to posts
• Extend that macro to generate a useful output for people using browsers with JS disabled
• Figure out how to edit asciicast recordings
• Is it possible to serve+play compressed asciicast?
• I’ve noticed a small bug, where if a recording is started with a manually-specified tty size, and that size is bigger than the terminal it’s run in, the terminal output is a mess. Report this bug, or better submit a PR to fix it (maybe by spitting out a warning before recording starts).

Sanitising Shell History

Lately I use zsh configured with a practically-infinite command line history, and with fzf setup to handle the Ctrl+r searching through that history. This combination of functionality is like a superpower, which I use frequently. However, for screen recording I feel like that long history is also a liability in that I’ve probably got some information in the history that’s better kept private. In a recording meant to show some firmware bug, there’s no need to reveal that I’ve used a command line tool to download a banjo video for offline practice!

So, I’ve made a couple little changes. First, I created a directory ~/.config/asciinema-zdotdir and put a .zshrc in there containing:

source ~/.zshrc export
HISTFILE=~/.config/asciinema-zdotdir/.sanitized_history

Then, in my ~/.zshrc file, add a function to record a tmux session:

function record-tmux {
  asciinema rec --tty-size 120x24 --input --overwrite -c "tmux new -e ZDOTDIR=$HOME/.config/asciinema-zdotdir" "$1"
}

Now, when record a tmux session using that function, Ctrl-R only shows the commands that I’ve run in other recorded sessions.