Sign up ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free.

It's unclear to me what the format is, if there's systematic/command-line requirements for creating it, etc.

Basically, just to need to know the specs, and if there's technical steps for generating the README file.

share|improve this question
Nope, just a text file that you edit by hand. As for the syntax, – Andrea Jan 5 '12 at 23:46
its the same wiki-edit-format that this side uses. – k3b Jan 5 '12 at 23:57
+1 @Andrea: Thanks, though I'm able to think of more than a handful of markdown formats, which format and version is expected on Github? Also, you comment reads as more of an answer, please post it as a complete answer. Again, thanks! – blunders Jan 6 '12 at 0:11
+1 @K3b: Believe you're on to something, are you talking about Github's use of Gollum, which for example allows relative linking? If so, please post this as the answer, as I believe that's the correct answer. Thanks! – blunders Jan 6 '12 at 0:20

3 Answers 3

up vote 37 down vote accepted

Markdown is a simple syntax for providing semantic info and representing common formatting in plain text. Daring Fireball has a awesome syntax guide for standard markdown. GitHub then uses a variant of this that they call GitHub Flavored Markdown.

To set up your readme just create a plain text file and name it README (or / README.markdown) and commit it to the root of your repo. GitHub will then pick this up as the project readme.

share|improve this answer
I also created a video explaining how to use Markdown. You can find it here: – Mike McLin Mar 25 '13 at 15:59

In the wikipedia link that Andrea posted in his comment, there's this link in the "References" list at the bottom of the page:
"GitHub Flavored Markdown - Introduction"

Quote from the link:

GitHub uses what we're calling "GitHub Flavored Markdown" (GFM) for messages, issues, and comments. It differs from standard Markdown (SM) in a few significant ways and adds some additional functionality.

After that comes a description of the differences to standard Markdown (see the link).

There's also more information how Markdown is actually rendered by GitHub:

If you're interested in how we render Markdown files, you might want to check out Redcarpet, our Ruby interface to the Sundown library.

--> Apparently, Sundown is the actual Markdown parser that is used behind the curtains.

To add one more layer of abstraction, Sundown is a fork of even another Markdown parser :-)
Quote from Sundown's GitHub page:

Sundown is a Markdown parser based on the original code of the Upskirt library by Natacha Porté.

share|improve this answer

It's very strange, but it looks as though GitHub doesn't use GitHub-Flavoured Markdown (GFM) when rendering a README file.

GitHub uses "GitHub Flavored Markdown," or GFM, across the site--in issues, comments, and pull requests.

Instead it seems to use a version called redcarpet as part of the GitHub markup project. They also support several other markup formats, including MediaWiki. Just use the right file extension, and GitHub will render the markup.

If you want to see the differences between the two different flavours of Markdown, read the description of GFM and its extra features.

share|improve this answer

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.