Working with README.md on github.com

Question

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?

Answer 1

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.

Answer 2

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

Answer 3

There's a nice online/live editor here:

http://jbt.github.io/markdown-editor/

There's also a Preview button at GitHub.

See in the following screenshot that this button appears when I clicked Edit on README.md.

IMHO the live editor is better than the current one available at GitHub.

UPDATE

Just now I found after searching for Markdown and Visual Studio that if you're using VS, you can install Web Essentials and have Markdown support right from within Visual Studio. That's cool!

It has:

• Syntax highlighting => Full colorization for Markdown syntax
• Intellisense for embedded languages (W00T) => GitHub's embedded language feature is fully support by support for the ```language syntax.

• Preview window => See a side-by-side preview window of the rendered HTML
• Compile to HTML => Right-click any Markdown file and select Compile Markdown to HTML. This will generate a .html file nested under the Markdown file and it will stay in sync as the Markdown file changes.
• Custom Stylesheet => You can add a solution specific Stylesheet to control the styles of the preview window.

Details about it here.

Answer 4

Note that since February 2014, with "Rendered Prose Diffs", you also can see the rendered version of a diff on a markdown file:

Commits and pull requests including prose files now feature source and rendered views.

Non-text changes appear with a low-key dotted underline. Hover over the text to see what has changed:

Answer 5

Another option - Github's new text editor, Atom, will render github-flavoured markdown as you edit it. See https://atom.io/

I'm not sure whether it will be free (as in beer) in the long term.

Answer 6

As of today, you can preview, as you edit the file.

Answer 7

I didn't find that the other tools were good enough - I wanted:

1. Ability to edit offline
2. Not just regular markdown, but the actual Github flavored markdown

This is what I ultimately settled on: https://github.com/ypocat/gfms

> gfms

Github Flavored Markdown Server.
Run in your project's root directory.
Usage: gfms

Options:
  -p, --port              Port number to listen at.        [required]
  -h, --host              Host address to bind to.         [default: "localhost"]
  --proxy                 if behind a proxy, proxy url.
  -a, --api               Render using Github API.
  -n, --no-api-on-reload  Disable usage of Github API when the doc is manually reloaded.

So I've aliased:

alias gm='gfms -a -p 8070'

Using the -p option hits the Github API and uses the actual, current Github CSS so there aren't any surprises.