27

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.

  • 4
    Nope, just a text file that you edit by hand. As for the syntax, en.wikipedia.org/wiki/Markdown – Andrea Jan 5 '12 at 23:46
  • 3
    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
37

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.md / README.markdown) and commit it to the root of your repo. GitHub will then pick this up as the project readme.

9

Wikipedia — Markdown references the page "GitHub Flavored Markdown - Introduction" (archv.)

Quote from the page:

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.

The page also gives a description of the differences to standard Markdown.

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

1

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.

  • 1
    redcarpet and Github Flavored Markdown are two separate, but complementary concepts, not competing implementations of the same thing. redcarpet is basically a compiler that takes things written in the Github Flavoured Markdown language and outputs HTML or XHTML. – 8bittree Feb 18 '16 at 21:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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