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.
I hope this post fills in the void I stumbled upon when googling for useful pointers earlier today.
Very good!
ReplyDeleteYou can post any image from web, with url : http://*
Great idea. Will be implementing this technique for my project screenshots as well.
ReplyDeleteThank you for sharing!
Devon
Hey Jef,
ReplyDeleteI 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!
Sorry Jef, I'm an idiot ... ignore the above. :)
ReplyDeleteHa! It never happened ;)
Delete:-D
DeleteGot it all working - thanks for posting, it's a much better way of handling this sort of thing!
Thank for your sharing.
ReplyDeleteHajime
Thanks for sharing!
ReplyDeleteGreat idea . Will be implementing this technique for my project screenshots as well.
ReplyDeleteWill be implementing this technique for my project screenshots as well...!!
ReplyDeleteGood 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.
ReplyDeleteSpot on! exactly what am looking for.
ReplyDeletewiki