Working with README.md on github.com [closed]

I am not too familiar with the lightweight markup language used by github when updating README files.

Where are the resources which I can read up on how to write the appropriate markup syntax for my open source library's README/wiki files?

And is there a tool which I can "review my docs locally in my browser" before pushing the updated README to my github repository?

The markup in question is coincidentally called Markdown, created by John Gruber, author of the Daring Fireball blog. The original source of Markdown can be found at Daring Fireball - Markdown.

There are many Markdown dialects, the documentation for Github's can be found on the Github Flavored Markdown page.

nice tip from that page:

press M on any Github page with a Markdown editor to reveal the cheatsheet.

You can also use the Github Markdown Live Preview page to test your Markdown documents.

Update 2012-11-08: Efforts are underway to standardize the Markdown syntax. See The Future of Markdown - Jeff Atwood, Coding Horror and W3C Markdown Community Group.

Update 2014-09-09: CommonMark a markdown standard and spec has been released.

(Re-posting this answer with some edits.)

A little late to the game, but I wrote a small CLI in Python. It's called Grip (Github Readme Instant Preview). Adding on to Patrick's answer, this will let you "review my docs locally in my browser."

Install it with:

$ pip install grip

And to use it, simply:

$ grip

Then visit localhost:5000 to view the readme.md file at that location.

You can also specify your own file:

$ grip CHANGES.md

And change the port:

$ grip 8080

Or combine the previous two:

$ grip CHANGES.md 8080

You can even render GitHub-Flavored Markdown (i.e. how comments and issues are rendered), optionally with repo context to auto-hyperlink references to other issues:

$ grip --gfm --context=username/repo issue.md

For brevity, see the rest of the options and their details using the CLI help:

$ grip -h

Notable features:

• Renders pages to appear exactly like on GitHub
• Fenced blocks
• Python API
• Navigate between linked files
• Export a rendered document to a file

Hope this helps. Check it out.