Create a great Github Readme with live local preview

The Readme is an afterthought, great code comes first?

When it comes to open source project documentation you can argue all you like about inline comments, wikis, and doc generation tools, however, there is no debate when it comes to writing a Readme. The Readme is the first thing that a user is going to see and if all of the other aforementioned items are missing that is OK but if a Readme is missing or weak your project is going nowhere. A well written Readme can make or break the spread of your open source project. Moreover, a Readme should be the genesis of your idea leading to the opinion of RDD or README Driven Development.

.. if a Readme is missing or weak your project is going nowhere.

Writing a great Readme starts with the right tools

Since at the time of this writing, Github being the de facto place for open source projects, let me introduce you to a fantastic tool for writing Github Readmes or any other Github page for that matter. With all the importance on Readmes it can be difficult to write a good one because the tooling isn't particularly great. Sure, many GUI-based editors have markdown viewers but what about console editors like Vim and Emacs. Even using good markdown viewer is an incomplete solution as Github has their own version of markdown, called Github-flavored markdown. Well, thanks to Daniel Marcotte we have a great Ruby gem called github-markdown-preview that will render a live local preview of Github-flavored markdown page. Let's explore why this gem is important and how to use it.

First, install the gem.

  $ gem install github-markdown-preview

For this article and screencast I am running v2.1.1 of the Gem within Ruby 1.9.3

This section is at the 1:29 mark in the screencast.

Next, I open up a tmux session with an open source project I am working on and from the Vim command line startup an instance of github-markdown-preview in the right pane.

"ts" is a bash function shortcut for a tmux send-keys command.

Within the right pane I copy the URL that github-markdown-preview generates.

Copying to the clipboard is done from Tmux copy mode.

I then paste that URL into the browser.

Live local preview of the Readme render with Github-flavored markdown.

This section is at the 3:09 mark.

What's also awesome about github-markdown-preview is that it automatically recognizes changes. Here is I delete the word "omitted" and save the README.

Now I reload the browser and the word "omitted" has been removed. This demonstrates github-markdown-preview's ability to regenerate the view based on changes to file it is watching.

The `github-markdown-preview` gem doesn't need to be restarted each time after a modification.

That concludes Create a greate Github Readme using a live local preview

I think that will get you started and truly there is not that much more to present as it is that simple to use. Now comes the harding part ‐ putting in the time and effort to make the Readme outstanding. I should also mention that creating a Readme pull request is a great way to break into contributing to other open source projects when looking to get your feet wet in that area. Generally speaking, nobody likes to documentation so project maintainers are eager to merge in Readme PR's.

If you want to learn more about Tmux then check out my 9-part series.

Pushed on 08/11/2014 by Christian