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.
Top comments (8)
This article could have been more useful if there was a comparison of the recording terminal apps. These are some apps that should have been included:
(a) github.com/faressoft/terminalizer
(b) github.com/neatsoftware/term-sheets
(c) github.com/vvo/gifify
Thanks for the article.
Thanks for the feedback.
The goal of this article was just to give a quick and simple example of how it can be done and I showed the tools I use and I am most familiar with.
Of course, like everything, there might be many alternatives, some worse, some better. These are the ones I use and that works fine for me.
Thanks for the list. I have tried "terminalizer" in the past, but couldn't get it to work due to some node error.
I'm rather disappointed that there were no animated gifs in this article..
ahah, well dev.to file uploader doesn't support SVGs ;)
And my imagination was rather low when wrote this.
How do I stop these animations?
Thanks for the tips. I use ttyrec to record my term.
Well, it can even easier than that - nbedos.github.io/termtosvg/ .
cool! didn´t know about this. Thanks ;)