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.
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?
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
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.
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.