Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

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
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
up vote 38 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.md / 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
2  
I also created a video explaining how to use Markdown. You can find it here: mikemclin.net/markdown-syntax-language – Mike McLin Mar 25 '13 at 15:59

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

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
    
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 at 21:12

Your Answer

 
discard

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.