Asciinema is an excellent tool for recording and sharing terminal sessions. The project is open-source and available on GitHub. A key feature of asciinema is that it allows the viewer to copy-paste the text from the player itself directly. The result of a terminal recording is an editable text file with extension .rec. This file can be easily shared and embedded on any website. However, markdown does not support rendering asciinema recordings. Therefore, you will need to transform your asciinema recording into something that markdown can handle, such as .gif files. This post will show you step-by-step how to use asciinema to generate beautiful terminal recordings to enhance README.md files.

First, let’s see the help page of asciinema using the wonderful tldr project:

Recording a Terminal Session

To install asciinema, follow the official guide. Once you have it installed, you can start recording a terminal session using the following command:

1
asciinema rec demo.cast

The previous command will create a recording file named demo.cast, which you can replay directly in the terminal as follows:

1
asciinema play demo.cast

Insert the Recording in a README

Now that you have your session recorded, you need to transform the demo.cast into a .gif file, which can be inserted in your README.md. To do so, the asciicast2gif tool comes handy. It allows to generate a .gif files from .cast asciinema recordings. To install asciicast2gif using npm run the following command:

1
npm install --global asciicast2gif

Note: For asciicast2gif to work, you also need have ImageMagic installed on your system.

Once asciicast2gif is installed, make the file transformation as follows:

1
asciicast2gif -w 80 -h 30 demo.cast demo.gif

The previous command will produce a demo.gif file with 80 characters width and 30 lines of height. It can be inserted in README.md, just as any other image:

1
![demo](PATH_TO_FILE)

where PATH_TO_FILE is the path to your demo.gif file on GitHub.

I have used this method to add a terminal screencast in the README.md of DepClean (one of my tools), so that the users can easily grasp its basic usage.

Insert the Recording in a Website

To use asciinema on the browser, use the asciinema-player. You will need asciinema-player.css and asciinema-player.js. You can download the latest version of these files here. Then, use these files from page as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<html>
<head>
  ...
  <link rel="stylesheet" type="text/css" href="/asciinema-player.css" />
  ...
</head>
<body>
  ...
  <div id="demo.rec"></div>
  <asciinema-player src="/demo.cast"></asciinema-player>
  ...
  <script src="/asciinema-player.min.js"></script>
  <script> 
   AsciinemaPlayer.create('/demo.rec', document.getElementById('demo.rec'), {
      loop: true,
      cols: 120,
      rows: 25,
      autoPlay: true,
      terminalFontSize: "small"
   });
</script>
</body>
</html>