An image is worth a thousand words and sometimes it´s much easier to demonstrate how something works by using images or videos instead of just text.

A common technique that works very well with GitHub and Markdown, is to use an animated GIF or SVG files.

this or this shows this in action.

Looks cool, doesn't it?

The first thing a user sees in a GitHub project is its README. A good first impression is essential and can make a difference between keep reading or just close the page and look somewhere else.

With an animated image, the user can see immediately how the project works like, without having to read the entire README or to download the entire project to test himself locally.

This is much more engaging experience and personally, If I see a project with this, I am much more likely to keep reading with attention the docs and to use it.

On the other side, for some kind of projects like web applications, it´s almost always a no go, if I cant find quickly any kind of visual demo. It can be just simple screenshots but I want to see how it looks like.

I don't want to clone the repo, set it up, just to see if it´s worth visually.

But how can you create these animations?

Recording your terminal

If it´s enough for you to record your terminal window, you can use asciinema and svg-term-cli for it.

asciinema is a free and open-source solution for recording terminal sessions and sharing them on the web.

To install it, follow the installation guide for your operative system.

Then, open a terminal session and type:

asciinema rec myrecord.cast

This command will start a recording session and every command you type from now on will be recorded. To stop the recording, press CTRL+D.

Your recording will be saved with the name you specified when running the "rec" command, in this example "myrecord.cast".

Asciinema allows you to upload your recording to their website, but you would need to include their player in the project README, which doesn't play automatically and forces the user to click and be redirected to the Asciinema website to see it, so we will use another tool, svg-term-cli to generate a regular SVG file from the Asciinema recording.

svg-term-cli is a node tool, so you need to have node installed on your system and install it with NPM:

npm install -g svg-term-cli

This tool can take an Asciinema recording as input and generate an animated SVG file as output, that you can add to your project README file as a regular image.

To generate an SVG file from our previously recorded session, run:

cat myrecord.cast | svg-term --out myrecord.svg --window

svg-term-cli supports a number of flags that you can use to customize the output image. Please look in the project README for details.

And voilá. You have an animated SVG with your terminal session that you can include in your projects README file as a regular image.

Recording your entire screen

If you need to record more than your terminal window, you can tools like Peek for Linux or recordit for MAC or Windows to Record your screen and export as an animated GIF file.

GIF files can become very big easily, so try to record just the area of the screen you need and by a short amount of time.

You can then add it to your project README as a regular image.