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
-
4Nope, just a text file that you edit by hand. As for the syntax, en.wikipedia.org/wiki/Markdown– AndreaJan 5, 2012 at 23:46
-
3its the same wiki-edit-format that this side uses.– k3bJan 5, 2012 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!– blundersJan 6, 2012 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!– blundersJan 6, 2012 at 0:20
Add a comment
|
3 Answers
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.
-
2I also created a video explaining how to use Markdown. You can find it here: mikemclin.net/markdown-syntax-language Mar 25, 2013 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é.
answered Jan 6, 2012 at 0:28
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.
-
2redcarpet 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.– 8bittreeFeb 18, 2016 at 21:12