Add a screenshot to your Github repo README.md

Today I learned… that you can add images to a Github repository README.md file! I’m now drunk with power and the desire to decorate all my repos with screenshots.

In README.md:

![alt text](screenshots/filename.png "Description goes here")

This approach (with a relative filepath to screenshots/filename.png) assumes your screenshot is part of your repo. For student projects, personal work, and other small stuff, including screenshots in your repo is no biggie.

If you don’t want the screenshot in your repo, you can upload it somewhere else and link to it directly like so:

![alt tag](http://domain.com/path/to/img.png "Description goes here")

.png is the preferred file format.

To take a screenshot on a Mac, press COMMAND + SHIFT + 4 at the same time. By default, the screenshot is saved as a .png to your desktop.

Reasons why repo screenshots rule:

  • screenshots illustrate what the project does
  • they help distinguish your repos from one another
  • they can help you remember projects you worked on a while ago
  • they show off your ability to document your work*
  • save you from having to clone in a project and start up a server to remember what it looked like
  • make a pretty portfolio of your work

* Documenting your stuff helps future-you and everyone else you might ever work with (including maybe your manager or boss). The people who do well in their careers are often those who take the time to record what they did, how they did it, why they did it that way, and share it with others. The ability to document one’s work is something I always looked for when making a hiring decision.

Screenshot action shot:

Screen Shot 2014-09-10 at 10.16.02 AM

I don’t expect to win any graphic design awards here, but I can surf my own repos and remember what I did at a glance, which is pretty sweet.

4 thoughts on “Add a screenshot to your Github repo README.md”

  1. Thanks for the post! Any guidelines on formatting images for use in README.md files? What file sizes and dimensions look and scale best?

    1. You can make the image part of your repo itself, if you like.

      You can do this locally by going into your repo and creating a new folder. You might call it “screenshots”.
      Place an image in that screenshots folder, then push it to the repo like you would any file (which might be like git add, git commit -m “adding screenshot”, git push origin master).

Leave a Reply

Your email address will not be published. Required fields are marked *