Why?

In most cases, your projects README.md or documentation will be a new user’s first introduction to your project. As a resulting, it’s important to put your best foot forward and have your documentation demonstrate the quality of your project. So in response to a few questions I’ve recieved about the graphics used in my own README’s, I decided I’d make a post explaining the process for spicing up your projects with animated SVGs.
Now, I’m sure you’ve noticed how including effectively coordinated GIFs in a project README.md can provide immediate insight as to the functionality and capability of a new project and definitely make for a great starting-point. Though GIFs aren’t without their drawbacks. Specifically, their limited color pattern, immutability, and the file size necessary to maintain non-pixalated, fluid animations. Fortunately, these shortcomings are where SVGs thrive.

For the uninitiated, SVG stands for Scalable Vector Graphic which means that the image is created using mathematical calculations rather than using pixels to form lines and shapes. This essentially means that the image can be scaled to any size and the lines will remain crisp and clear.

svg

Nonetheless, it’s also important to note that there are still many places where custom animated SVGs aren’t supported, but luckily for us, GitHub (and this blog) both support animated SVGs with no-workarounds-needed.
Additionally, while this may be the most advantageous for command-line projects, these animated SVGs can be used for examples, installation instructions, or anything involving the command-line.

Getting Started

The first step is that you’re going to need to install asciinema and svg-term-cli. This will provide the terminal session recording and tool that we’ll use to create the animated SVG.
Once these are installed, you’ll want to create your recording. Using the following command will spawn a new shell instance and start your recording:

1asciinema rec <filename>

When your finished, you can stop the recording by typing exit or pressing ctrl+D. The recording will be saved as a .cast file, that you’ll be able to pass to svg-term-cli to create your animated SVG.
Once you’re satisfied with your recording, you can create your animated SVG with the following command:

1svg-term <filename(.cast)> --out <filename(.svg)> --window
example