Hosting screenshots on GitHub

December 29, 2012

The problem

I have some screenshots of an application that I want to put in my github repository’s README. Fortunately, github provides a feature that can be used to solve this problem, called github pages.

Github’s pages service provides a lot of useful resources for hosting a website about your project. However, if you’re just looking to host static content (such as images), pages will do the trick. Below, I’ll show how to host content on github pages in a couple of minutes.

Steps

  1. Create a new, empty branch called gh-pages
    cd repo-name
    git checkout --orphan gh-pages
    git rm -rf .
    rm -r .
  2. Add your static files
    Create an images/ folder in the root of the branch, and put your screenshots in that folder.
  3. Commit and push gh-pages branch to github
    git add images/*
    git commit -m "Added static images/ folder"
    git push -u origin gh-pages
  4. Switch back to your master repository
    git checkout master
  5. Link to your images in your markdown file
    # In your README.md file in your master branch:
    ![My Screenshot](http://username.github.com/repo-name/images/screenshot.png)

That’s it!

If you need to add new pictures to your repository, just switch to your gh-pages branch and push any other resources you need, then link to them in your README.

git checkout gh-pages
# Add content...
git commit -am "Added new images"
git push
git checkout master