ghpreview – gem to preview README files for Github

Article originally published in the Neo blog.

A while ago, Adam McCrea from the Neo Columbus office shared ghpreview. It’s a tool to preview a Markdown file locally with Github styling. It also has the option to refresh everytime you save your source Markdown file.

The most common use is your project’s README file before pushing it to Github. It also accepts any Markdown file. Even though there are many other tools to preview this kind of file, none of them use Github Flavored Markdown.

ghpreview is an accurate preview because it uses Github’s own HTML processing filters to generate the HTML, and Github’s own stylesheets to style it.

I found the gem extremely useful, it’s a great way to check your README files for Github projects before pushing them. So when Adam let us know about it I went and installed it with gem install ghpreview.

The gem wasn’t working for me, so I went and looked at the source code to check it out. I found out that once the markdown file had been processed, it was using the ‘open’ command to view the resulting HTML in the browser.

The open command in Mac OS X opens files and directories. In my system – Ubuntu 12.10 –, it starts a program on a new virtual terminal, so it wasn’t doing what was expected from the gem. What I had to use to open a file was xdg-open:

xdg-open is a desktop-independent tool for configuring the default applications of a user

This tool is included in most popular Linux distributions with a desktop environment. So I just had to make a small change in the code to support Linux on the gem:

if RUBY_PLATFORM =~ /linux/
  command = 'xdg-open'
else
  command = 'open'
end
`#{command} #{HTML_FILEPATH}`

And that was my first accepted pull request to ghpreview.

The way the gem worked, it downloaded the CSS from github and made a post to Github’s API to get the markdown file processed into HTML. Few days after ghpreview’s release, Github announced html-pipeline, a gem that includes several internal HTML utilities used in Github. This includes Markdown compilation and Syntax highlighting.

So my second pull request for the gem was to avoid going to the Github API and using html-pipeline instead. Stylesheets are still downloaded from Github, but they are cached for a week.

The gem is now at version 0.0.3, and I’ve been using it regularly when working on Markdown files. It really is a great tool and I’m happy I’ve been able to contribute to its development. Check it out on Github or just gem install ghpreview to start using it. Use ghpreview README.md to preview a file in your browser and add -w to for a live-updating preview whenever you save your file.