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. AnonymousMay 29, 2012 at 4:11 PM

    Very good!

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

    ReplyDelete
  2. DevonSeptember 28, 2012 at 9:16 PM

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

    Thank you for sharing!

    Devon

    ReplyDelete
  3. digitalformulaSeptember 30, 2012 at 4:43 PM

    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. digitalformulaSeptember 30, 2012 at 4:48 PM

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

    ReplyDelete
    Replies
    1. Jef ClaesSeptember 30, 2012 at 7:34 PM

      Ha! It never happened ;)

      Delete
    2. digitalformulaOctober 2, 2012 at 6:50 AM

      :-D

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

      Delete
  5. UnknownOctober 13, 2012 at 6:04 AM

    Thank for your sharing.

    Hajime

    ReplyDelete
  6. spencerOctober 19, 2012 at 5:10 PM

    Thanks for sharing!

    ReplyDelete
  7. Timnas Indonesia u-19May 8, 2014 at 6:42 PM

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

    ReplyDelete
  8. jambhuJune 21, 2014 at 8:02 AM

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

    ReplyDelete
  9. AnonymousNovember 5, 2014 at 4:15 PM

    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
  10. UnknownJuly 28, 2016 at 12:31 PM

    Spot on! exactly what am looking for.

    wiki

    ReplyDelete

Subscribe to: Post Comments (Atom)