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:
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”.
Hey, thats a good idea! I sometimes commit small changes to the README, but its a great idea to preview them locally first.
The python script worked but it has ffed up indent at the moment, maybe you can fix it for simple copy and paste?
Somehow it got messed up, thanks. Corrected.
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
Use ‘retext‘ to preview markdown and ReST when or after you edit your document.
Thanks, it seems useful.
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:
Update: Oops… forgot just to leave the location of README file configurable…
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?
Hmm, I didn’t notice that. I don’t know, try to ask the reText developers.
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.
I am actually using retext and uberwriter now… nice interfaces with live preview!