Next: On Org and Org Babel, Previous: About This Document, Up: Readme [Index]
Markdown is a text-to-HTML conversion tool for web writers.
Thus, “Markdown” is two things:
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible.
(click to download ==> ‘Markdown.pl’)2.
By default, Markdown produces XHTML output for tags with empty elements:
<br />
John Gruber’s canonical description of Markdown’s syntax does not specify the syntax unambiguously. ‘Markdown.pl’ was quite buggy, and gave manifestly bad results in many cases, so it was not a satisfactory replacement for a spec. Because there is no unambiguous spec, implementations have diverged considerably. As a result, users are often surprised to find that a document that renders one way on one system (say, a GitHub wiki) renders differently on another (say, converting to docbook using pandoc).
The CommonMark specification attempts to specify Markdown syntax
unambiguously. The examples are intended to double as conformance tests. An
accompanying script spec_tests.py
can be used to run the tests against any
Markdown program:
python test/spec_tests.py --spec spec.txt --program PROGRAM
‘GitHub Flavored Markdown’, often shortened as ‘GFM’, is the dialect of
Markdown that is currently supported for user content on GitHub.com
and
GitHub Enterprise.
‘GitHub-flavored Markdown’ is based upon the CommonMark Spec by John MacFarlane. This formal specification, based on the CommonMark Spec, defines the syntax and semantics of this dialect. GFM is a strict superset of CommonMark. All the features which are supported in GitHub user content and that are not specified on the original CommonMark Spec are hence known as extensions, and highlighted as such.
Some features of ‘GitHub Flavored Markdown’ are only available in the descriptions and comments of Issues and Pull Requests. These include ‘@mentions’ as well as references to SHA-1 hashes, Issues, and Pull Requests. Task Lists are also available in Gist comments and in Gist Markdown files.
This is a GitHub Guide, fairly simple in nature.
This is also a GitHub Guide, more extensive and advanced in nature than Mastering Markdown.
This is a GitHub Cheatsheet-style guide.
This is intended as a quick reference and showcase.
In the browser, add ‘index.text’ to the end of the URL to see the source.
Markdown requires the standard Perl library module Digest::MD5.
Next: On Org and Org Babel, Previous: About This Document, Up: Readme [Index]