Working with README.md on github.com
GithubMarkdownMarkupGithub Problem Overview
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?
Github Solutions
Solution 1 - Github
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.
Solution 2 - Github
(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.
Solution 3 - Github
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.
Solution 4 - Github
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:
Solution 5 - Github
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.
Solution 6 - Github
Solution 7 - Github
I didn't find that the other tools were good enough - I wanted:
- Ability to edit offline
- 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.