How to add GIFs in GitHub README Without Software

Ferruh Cihan
6 min readOct 16, 2020

--

In this article, we will share the best way to display your projects in GitHub README file.

GitHub is an excellent tool for developers and programmers. We can upload our codes on GitHub and work collaboratively with our colleagues. But what if we only want to show our projects without deploying or hosting anywhere?

I can hear you say, “we can use GitHub pages for easy deployment.” We can use GitHub pages for our simple projects containing HTML, CSS, or JavaScript files. I want to share an easy visual way with this article.

As you can guess from the title, this method is using GIFs in our README files. I think images and videos attract our attention more than lines of code.

At this point, we have to decide how we want to proceed. We can use screen capture or video to show our projects. In our README files, if we use images, we can’t show the entire project, or if we use videos, we should add video links that force the user to open a new page.

We can use GIFs in a unique method to help us, especially when we cannot use GitHub pages as in React Native Projects.

Let’s begin.

First of all, we need a video that shows us our project details to create a GIF. OK, how can we record our project? We don’t need to download or install any software. We can use default programs for recording on both macOS and Windows 10.

How to record the screen on Mac? ( Shift + Command + 5 )

If you’re using macOS Mojave or later, press Shift + Command (⌘) + 5 on your keyboard to see onscreen controls for recording the entire screen, recording a selected portion of the screen, or capturing a still image of your screen. You can also record the screen with QuickTime Player instead.¹

For more information [video][text].

How to record the screen on Windows 10? ( ⊞ Win + G )

Suppose you’re using Windows 10, press ⊞ Win + G on your keyboard to see onscreen controls for recording the program windows. There is an exception for Windows 10. You can’t record the entire screen or more than one window. You can record just any program window like browser, code editor, or virtual emulator. So you should open the program which you want to record before pressing ⊞ Win+G

For more information [video] [text]

Please don’t worry. Below I show a sample project in practice. 😊

How to create a GIF using screen recording?

After the recording, we can create a GIF as we want. At this point, we need to use a website to create a GIF. You can choose any website that offers make a GIF from video. I prefer ezgif.com. It is easy to use and doesn’t require sign up. I will show you how to use the website for nearly all the details.

How to add the GIF in GitHub README file?

This issue is straightforward. We can add the GIF in README like adding any image. We have two options for adding an image in README.

  1. We can add as a markdown image:
![screen-gif](./myScreen.gif)

2. We can add as an HTML <img> tag:

<img src="./myScreen.gif" alt="My Project GIF" width="500" height="600">

Sample React Native Project and GitHub README File

So far, we have seen what we need and are used for. But we didn’t apply them. Let’s create a new React Native project and add the project’s GIF in the README file.

Note: You can use this method for any project, not just React Native 😉.

As you see below, I created a sample React Native Project to explain the entire process. And I use Genymotion for the virtual device. I will start the recording by using Genymotion Virtual Smart Phone.

1. First of all, I suggest you minimize all windows except your project’s window. This will protect you from the complication.

2. Open the just Genymotion window (or another program which you want to record) then press ⊞ Win + G on your keyboard.

3. To start the recording, click 1️⃣ the record button or press ⊞ Win + Alt + R on your keyboard. If the capture window doesn’t open, you can open by clicking on 2️⃣ the capture button.

4. After the start, you can record the video and show what you want about your project. You can see the duration of the video on the recording bar.

5. When you click the stop button on the recording bar, the video will be recorded. And you can see the recorded alert on the right side of the window.

6. Then, open the ezgif.com on the browser. Upload the video to this website. Please pay attention to the video file size. You can upload MP4, WebM, AVI, MPEG, FLV, MOV, 3GP, and other video files, but the maximum file size is 100MB!

7. After uploading, you can manipulate your video. You can cut the video, change speed, or decide the start & end time to create the GIF. You can change the frame rate related to the video duration. Higher frame rates provide more quality 👌. After completing all the adjustments, you can click the “Convert to GIF!” button.

8. After a while, your GIF will be created. Then you can download your GIF by right-click + Save image as shortcut.

9. OK, we have the GIF. Let’s add this GIF to our GitHub README file in our project.

10. We should move the GIF to our project folder. Then we can create the README.md file in the project folder. At last, we can write the link of our GIF into our README file.

11. Finally, we can push our project to GitHub and check the Sample React Native Project repository and the README file. 😊

Happy coding…

Note 1: You can check this README file on GitHub.

Note 2: You can also check this project with this link React Native Sample Project.

You can share your opinions and comments below.

You can contact me via Twitter, Medium, GitHub for your questions and to contribute.

[1]: How to record the screen on your Mac,
https://support.apple.com/en-us/HT208721?cid=ytsc_yt100

--

--