README.markdown on GitHub

For a quick and painless solution check out the last update at the end of the post.

When you create a project on GitHub, it is highly encouraged to add a README file too. Thus, when someone visits your project’s page, they will see the content of your README file automatically (example).

If you want, you can use the markdown syntax in your README files. In this case don’t forget to rename the file to README.markdown. It has the advantage that the output is much nicer while the source remains readable in a normal text editor too (example).

Update: You can also name the file as README.md. In the future I’ll use the .md extension, it’s shorter and simpler.

To learn more about the markdown syntax, refer to these links:

• GitHub Flavored Markdown
• Markdown Syntax Guide
• Markdown Basics
• markdown at wikipedia

Problem

When I write a README.markdown file, I’d like to visualize it before uploading to GitHub. If there is a problem, I don’t want to commit this file several times. I’d like to refine it on my local machine and when it’s good, I want to upload it once.

Solution

I came up with the following Python script to visualize marked up files:

import os
import sys

MARKDOWN = 'markdown'
UPSKIRT = 'upskirt'

PROGRAM = MARKDOWN
VERBOSE = True

def main():
    update = False

    if len(sys.argv) < 2:
        print "Usage: {0} <file.markdown> [-u]".format(sys.argv[0])
        sys.exit(1)
    # else
    if '-u' in sys.argv:
        update = True
        sys.argv.remove('-u')
    input_file = sys.argv[1]
    os.system("{program} {input} > /tmp/markdown.html".format(program=PROGRAM, input=input_file))
    if not update:
        os.system("chromium-browser /tmp/markdown.html &")
    if VERBOSE:
        print >>sys.stderr, "# renderer: {0}".format(PROGRAM)

#############################################################################

if __name__ == "__main__":
    main()

The up-to-date version of the script is available in this GitHub repository.

Usage: put it in your ~/bin directory (make sure ~/bin is in your PATH), make it executable (chmod u+x ~/bin/markdown.py), and call it as “markdown.py README.markdown“. It will open the HTML output in a new tab. Adding the “-u” switch (update), the HTML is not opened in the browser.

Typical usage: call it first as “markdown.py README.markdown“, then add the “-u” switch and refresh the output in the browser.

Ref.: I saw this idea here but I couldn’t make it work with Ruby. I added the “-u” switch to make it easier to use.

Update (20110507)

First, I managed to install redcarpet. It was not easy… I wrote a post about it.

Second, if you want to use the GitHub flavored markdown, you don’t need to install redcarpet. I figured out later that redcarpet is just a Ruby wrapper for upskirt. So you can use upskirt directly. It’s written in C, just compile it and use the executable binary “upskirt“. This is integrated in the new version of the script (available here).

Update (20120212)
The “upskirt” project is gone from Github. It is replaced by sundown. Sundown is a fork of upskirt and this is the version used by Github too.

Update (20120219)
As it was pointed out by Teodor in a comment, the easiest way is to use the text editor ReText. It has a live preview function (Ctrl+Shift+E), thus editing Markdown or reStructuredTexts is made trivial. ReText is written in Python by the way.

Update (20141203)
I found an even nicer editor for markdown files: Remarkable. I write about it here.

Update (20150820)
Here is the ultimate solution :) Use the Atom editor with the markdown-preview package. Open a rendered version of the Markdown in the current editor with “Ctrl-Shift-M”.