DEV Community

Kelli Blalock
Kelli Blalock

Posted on

Demo your App in your GitHub README with an Animated GIF

I have my GitHub link on my resume and if I'm lucky, potential employers might check out my apps on GitHub. However, I know they're busy and won't have much time to spend so I wanted to make it easy for them and others visiting my repo and show the app in action in the file that's displayed when you go to a repository.

Embedding a video in a GitHub README would be a dream come true, but as I found out, it's not possible--you'd have to link to the video instead. You can, however put an animated GIF in a README file and that's what I've done with many of my projects.

Here's one for my Farmer's Market Finder app:

App Demo

Unfortunately, animated GIFs can't normally be as long as videos, but you can use them to quickly show off some core functionality of your app.

How to Create an Animated GIF?

Here are a couple apps you can use to create animated GIF screen recordings.


I like to use ScreenToGif which is a free open source app for Windows 7 or later. The software is intuitive to use for simply creating an animated GIF of an area you choose on your screen and they also have a User Guide.


I use Gifox when creating animated GIFs of my screen on the Mac. It sits up in my menu bar and is easy to use. I use the paid version because GIFs created with the free version are limited to 10 seconds and have a watermark.


I know I've left out options for other operating systems and devices, but I only wanted to recommend the ones I've tried myself. Please comment below if you can recommend other apps for taking animated GIF screen recordings.

Adding the Animated GIF to your README

Once you've created the animated GIF, you can embed it in your file like you would a regular image.

I usually create a 'Demo' Heading in my README under the description of the app and put the animated GIF under the Demo heading along with a link to a demo of the site online.

If you don't have a good place to host images, you could do what I have done and create a demo (or better named) folder in your GitHub repository and upload the GIF there, then link to it in the README.


![Farmers Market Finder Demo](demo/demo.gif)

Note: The alt text is what goes between the square brackets and then the URL to the GIF goes between the parentheses. If the image is in your GitHub repository, you can use a relative link like I did in the example.

Thanks for reading my first post!

Top comments (22)

brpaz profile image
Bruno Paz

For Linux, you can use Peek.

priteshusadadiya profile image
Pritesh Usadadiya • Edited

I use screencastify plugin for chrome to record product workflows, bugs etc...

In Free tire it gives you 50 recordings per month with max 10 min. recording per session. you can download saved videos from Google drive or export it as gifs.

i have been using it for some time and never needed to upgrade to paid plan.

kelli profile image
Kelli Blalock

Thanks Pritesh, screencastify looks good. I'll definitely give it a try!

gradientus profile image
Phil Mauracher

While it is true you have 50 free recordings a month. You must pay $24 a year to make animated gifs. However, it's money well worth it to make quality README files.

itsasine profile image
ItsASine (Kayla)

I use GIPHY Capture on Mac. While the purpose is to upload gifs to giphy, I just save them locally after capturing my screen. I also save the gif in the repo itself rather than try to keep things hosted in one place. If the app changes, then I can just update demo.gif while I'm in there and it's all in one commit.

voyz profile image

Fantastic post! I just wrote a post on adding large GIFs to the, expanding on what you discuss at the end regarding adding the GIF into the repo. Thanks for writing this Kelli 😊

foodogsquared profile image
Gabriel Arazas • Edited

It's a great idea! I've done something like this occasionally but I never thought about fully committing to the idea (though the recording length can be a problem).

As for a GIF capturing tool, I use ShareX (only for Windows) though you have to download an encoder for it which ShareX will just prompts you for it so no worries about looking for it. Overall, it's a great tool! You can capture it in MP4, JPG, and PNG. You can also upload it on different image hosting sites, too.

z2lai profile image

ShareX is incredible for a free software. You can set it to capture a specific region of your screen as a video or GIF. You can also use it to convert videos into GIFs.

emgodev profile image

Might be a good idea in general to host such media externally, I suppose most important for long-term projects. I've tried this out recently, much smaller imprint to update a url path than for a repo to contain a media file it does not need.

emgodev profile image

But this is a good idea! I've tried including demos as a frontend model in a few repos as a directory, but a GIF gives that immediate impression.

ayyappa96805355 profile image
ayyappa • Edited

with your help i have added demo gif for my project in github. thank you.

marissab profile image
Marissa B

That's pretty clever! Good tip.

ewoks profile image

Check super simple, grat tool

mertcansegmen profile image
Mertcan Seğmen

This is very helpful, thank you!

ayyappa96805355 profile image


jairajsahgal profile image

It's not showing in your README now

gledsonafonso profile image
Gledson Afonso

Thanks for the ScreenToGif recommendation!

mersadajan profile image
Mersad Ajanovic

Thanks for the tip! Just bought Gifox and it's fantastic!

ajinkyax profile image
Ajinkya Borade

once you have the GIF image. I create issue on github, then drag and drop the file in textarea. Cope the MD code, cancel the issue.

Take the code line to README :)

cubiclesocial profile image

I know I'm late to this, but you should always create the issue and then close it. Otherwise, GitHub/Microsoft might, in the future, delete images that use this hack to basically turn GitHub into an upload site. How many people have started the process of opening an issue, uploaded an image, and then cancelled because they figured out the problem themselves or are abusing the CDN this way? Probably way more than have used this hack for repos. Those images occupy space on a drive somewhere and someone is going to want to reclaim that wasted storage space after a while.