Home > python > README.markdown on GitHub

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:


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.


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

import os
import sys

MARKDOWN = 'markdown'
UPSKIRT = 'upskirt'


def main():
    update = False

    if len(sys.argv) < 2:
        print "Usage: {0} <file.markdown> [-u]".format(sys.argv[0])
    # else
    if '-u' in sys.argv:
        update = True
    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__":

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”.

  1. May 5, 2011 at 23:42

    Hey, thats a good idea! I sometimes commit small changes to the README, but its a great idea to preview them locally first.

  2. June 16, 2011 at 06:14

    The python script worked but it has ffed up indent at the moment, maybe you can fix it for simple copy and paste?

    • June 16, 2011 at 06:21

      Somehow it got messed up, thanks. Corrected.

  3. February 18, 2012 at 14:09

    If you use vim, I wrote a vim plugin to visualize github-flavored-markdown files in real-time: https://github.com/suan/vim-instant-markdown

  4. Teodor
    February 19, 2012 at 12:11

    Use ‘retext‘ to preview markdown and ReST when or after you edit your document.

  5. March 2, 2012 at 12:29

    Hum…. my 2 cents on this:

    – I felt little need to have argument parsing for a such simple script, specially because I am looking only for checking the markdown of a README file, and nothing else
    – chromium-browser may not be installed in the machine executing it, furthermore, its name has been changed in latest repository to: google-chrome… so, a better solution, IMO, is to use the system’s default browser (with the command xdg-open)

    Here is the script I am using:

    import os
    import sys
    PROGRAM = "markdown"
    The markdown parser program.
    OUTPUT = '/tmp/readme.markdown.html'
    The temporary location for the HTML rendered file based on the README markdown.
    def main():
        if os.system("which %s" % PROGRAM) != 0:
            print """%(script)s script requires %(program)s program. 
    In Ubuntu, you can simply install it by executing: 
            sudo apt-get install %(program)s""" % {'script': __file__, 
                                                   'program': PROGRAM}
        os.system("%s ../README > %s" % (PROGRAM, OUTPUT))
        os.system("xdg-open %s &" % OUTPUT)
    if __name__ == "__main__":

    Update: Oops… forgot just to leave the location of README file configurable…

  6. didievmdkdiefjeiecidkejfm
    April 21, 2012 at 20:15

    I installed reText as you suggested, but it seems to be using standard markdown instead of github-flavored markdown. How do I teach it to use github-flavored markdown?

    • April 21, 2012 at 20:37

      Hmm, I didn’t notice that. I don’t know, try to ask the reText developers.

  7. cjstokyo
    June 24, 2013 at 05:27

    Seems a lot easier and more portable to use a simple shell script. Note that this also does proper temporary file handling, giving it a name that should be unique and cleaning it up properly afterwards.

        #  mdpreview - preview a markdown file
        #  Idea from:
        #    https://ubuntuincident.wordpress.com/2011/05/05/readme-markdown-on-github/
        #  This does not handle the Github variations documented at:
        #    https://help.github.com/articles/github-flavored-markdown
        #  You may want to try using a gist to get a more accurate preview.
        #    https://gist.github.com/
        #  To-do: add an option to keep running in the background, monitoring the
        #  input file, and, when it changes, regenerate the HTML file and have
        #  the browser reload it.
        set -e
        err() { echo 1>&2 "ERROR: $@"; exit 1; }
        markdown --version >/dev/null 2>&1 \
            || err "Cannot execute 'markdown' program (install 'markdown' package?)"
        tmpfile=$(mktemp --tmpdir $(basename $0).XXXXX.html)
        trap "rm -f $tmpfile" EXIT
        markdown > $tmpfile "$@"
        # Should be be using xdg-open instead?
        # Does sensible-browser background automatically when no browser is running?
        sensible-browser $tmpfile  
        sleep 1                     # Give browser a chance to load page
  8. June 24, 2013 at 07:23

    I am actually using retext and uberwriter now… nice interfaces with live preview!

  1. November 16, 2011 at 14:38

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: