Sunday, April 1, 2012

Add images to a GitHub readme

Today I wanted to add some screenshots to a GitHub readme for the sake of documenting. While this wasn't particularly hard, I do had to iterate a few times before I got it right.

Hosting the images

You could simply add the images to your repository and reference them using the raw url's, but this isn't very efficient. Using this method, every request needs to go through GitHub's application layer. It's far better to make use of GitHub Pages, a feature purely designed to publish web content. I also like how you're not polluting the repository this way.

Referencing the images

I'm using the - oh so beautiful and simple - markdown format for most of my readme's. The syntax for embedding images looks like this.

![My image](username.github.com/repository/img/image.jpg)

I hope this post fills in the void I stumbled upon when googling for useful pointers earlier today.

12 comments:

  1. Very good!

    You can post any image from web, with url : http://*

    ReplyDelete
  2. Great idea. Will be implementing this technique for my project screenshots as well.

    Thank you for sharing!

    Devon

    ReplyDelete
  3. Hey Jef,

    I followed the Github doco (https://help.github.com/articles/creating-project-pages-manually) to create a page but only added a single image to it. That works fine if I browse that branch but referencing files in that branch from the master branch produces a 404 - e.g. https://github.com/digitalformula/zsh.prompts has a 404 on the image at the bottom of the README content.

    How did you get around that? Or am I missing a key point?

    Great idea, otherwise!

    ReplyDelete
  4. Sorry Jef, I'm an idiot ... ignore the above. :)

    ReplyDelete
    Replies
    1. :-D

      Got it all working - thanks for posting, it's a much better way of handling this sort of thing!

      Delete
  5. Great idea . Will be implementing this technique for my project screenshots as well.

    ReplyDelete
  6. Will be implementing this technique for my project screenshots as well...!!

    ReplyDelete
  7. Good point, however you should maybe make more explicit that Github Pages is actually a branch in the repository, i.e. the content is downloaded when cloning.

    ReplyDelete
  8. Spot on! exactly what am looking for.

    wiki

    ReplyDelete