picture of Josh Dzielak in 2016

Hi! I'm Josh Dzielak, writing here about technology and culture. Find me also on Twitter, Medium, Speakerdeck and Github.

Preview your Github README.md locally

A good README.md is an essential tool to educate developers about your Github-hosted project.

Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.

Often times, you’ll want to preview or iterate on your README before you publish it.

While Github is the only place you’ll get a perfect preview (github uses github flavored markdown, it’s a tedious process to commit, push, check, and repeat. This triggers hooks, adds to your repository, something about kittens, etc – all stuff you don’t want.

A better solution is to iterate and preview locally. You might not get all of the Github markdown goodness, but you’ll be close.

Here’s a gist that’ll help you set up a simple README.html in your repository that reads right from from your README.md and displays it. (Bonus: It also includes hotlinked Github CSS (like a boss) so you can get an even better feel for how it’ll look for your Github audience.)


Here’s a small repository I created to illustrate this concept. You can clone it, stick it under your web server, and hit README.html to see it in action.