Markdown

Markdown is a lightweight markup language, originally created by John Gruber and Aaron Swartz allowing people "to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)".^[1] The language takes many cues from existing conventions for marking up plain text in email.

Markdown is also a Perl script written by Gruber, Markdown.pl, which converts marked-up text input to valid, well-formed XHTML or HTML and replaces left-pointing angle brackets ('<') and ampersands with their corresponding character entity references. It can be used as a standalone script, as a plugin for Blosxom or Movable Type, or as a text filter for BBEdit.^[1]

Markdown has since been re-implemented by others as a Perl module available on CPAN (Text::Markdown), and in a variety of other programming languages. It is distributed under a BSD-style license and is included with, or available as a plugin for, several content-management systems.^[2][3]

Syntax examples

This is not an exhaustive listing of Markdown's syntax, and in many cases multiple styles of syntax are available to accomplish a particular effect. See the full Markdown syntax for more information. Characters which are ordinarily interpreted by Markdown as formatting commands will instead be interpreted literally if preceded by a backslash; for example, the sequence '\*' would output an asterisk rather than beginning a span of emphasized text. Markdown also does not transform any text within a "raw" block-level XHTML element; thus it is possible to include sections of XHTML within a Markdown source document by wrapping them in block-level XHTML tags.

Paragraphs

A paragraph is one or more consecutive lines of text separated by one or more blank lines. Normal paragraphs should not be indented with spaces or tabs:

This is a paragraph. It has two sentences.

This is another paragraph. It also has 
two sentences.

Line return

Line breaks inserted in the text are removed from the final result: the web browser is in charge of breaking lines depending on the available space. To force a line break, insert two spaces at the end of the line.

Emphasized text

*emphasis* or _emphasis_ (more common)  (e.g., italics)

**strong emphasis** (more common) or __strong emphasis__ (e.g., boldface)

Code

To include code (formatted in monospace font), you can either surround inline code with backticks (`), like in

Some text with `some code` inside,

or indent several lines of code by at least four spaces, as in:

    line 1 of code
    line 2 of code
    line 3 of code

The latter option makes Markdown retain all whitespace—as opposed to the usual behaviour, which, by removing line breaks and excess spaces, would break indentation and code layout.

Lists

* An item in a bulleted (unordered) list
    * A subitem, indented with 4 spaces
* Another item in a bulleted list

1. An item in an enumerated (ordered) list
2. Another item in an enumerated list

Headings

HTML headings are produced by placing a number of hashes before the header text corresponding to the level of heading desired (HTML offers six levels of headings), like so:

# First-level heading

#### Fourth-level heading

The first two heading levels also have an alternative syntax:

First-level heading
===================

Second-level heading
--------------------

Blockquotes

> "This entire paragraph of text will be enclosed in an HTML blockquote element.
Blockquote elements are reflowable. You may arbitrarily
wrap the text to your liking, and it will all be parsed
into a single blockquote element."

The above would translate into the following HTML:

<blockquote><p>This text will be enclosed in an HTML blockquote element. Blockquote
elements are reflowable. You may arbitrarily wrap the text to your liking, and it will all
be parsed into a single blockquote element.</p></blockquote>

Links

Links may be included inline:

[link text here](link.address.here "link title here")

Alternatively, links can be placed in footnotes outside of the paragraph, being referenced with some sort of reference tag. For example, including the following inline:

[link text here][linkref]

would produce a link if the following showed up outside of the paragraph (or at the end of the document):

[linkref]: link.address.here "link title here"

Horizontal rules

Horizontal rules are created by placing three or more hyphens, asterisks, or underscores on a line by themselves. You may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:

* * *
***
*****
- - -
---------------------------------------

Markdown users

• Bitbucket offers Markdown as an option for markup in project's README.^[4]
• DIASPORA* uses Markdown to format user posts, comments and conversations .^[5]
• Drupal has a Markdown add-on^[6], initiated in 2008. As of November 2011 it in use on over 8000 Drupal sites world-wide.
• GitHub uses a dialect of Markdown for formatting comments, messages, etc.^[7][8] John Gruber has described this dialect as a "superior variant" for "situations like user-submitted comments".^[9]
• G+ Tweaks v1.1151, a Greasemonkey user script for adding functionality to Google's G+ social networking site.^[10]
• Instiki uses a Markdown extension to wiki syntax. The extended syntax is called Maruku.^[11]
• Posterous offers Markdown as a markup option.^[12]
• Reddit uses Markdown.^[13]
• Showoff uses Markdown to format slides of a presentation.^[14]
• Squarespace offers Markdown as a blog entry option.^[15]
• Stack Overflow and other Stack Exchange Network sites use a modified dialect of Markdown as its default formatting system.^[16][17]
• Tumblr allows Markdown edits to posts.^[18]
• The WordPress plugin system utilizes a dialect of Markdown in "readme.txt" files submitted by developers, and has plugins for Markdown.^[19]

See also

• Markdown extensions
• reStructuredText is a similar lightweight markup.
• Textile, a similar lightweight markup
• Markdown Extra is based upon Markdown but extends its capabilities.
• MultiMarkdown is another improved Markdown with more syntax-features and export-options than traditional Markdown.
• Asciidoc another lightweight markup supporting many types of document.

References

1. ^ ^{a b} Markdown 1.0.1 readme source code "Daring Fireball - Markdown". 17-Dec-2004. http://daringfireball.net/projects/markdown/. 
2. ^ "MarsEdit 2.3 ties the knot with Tumblr support - Ars Technica". http://arstechnica.com/apple/news/2009/03/marsedit-23-ties-the-knot-with-tumblr-support.ars. Retrieved 2009-08-11. 
3. ^ "Review: Practical Django Projects - Ars Technica". http://arstechnica.com/open-source/news/2008/07/review-practical-django-projects.ars. Retrieved 2009-08-11. 
4. ^ "Displaying README Text on your Bitbucket Source Tab". http://confluence.atlassian.com/display/BITBUCKET/Displaying+README+Text+on+your+Bitbucket+Source+Tab. Retrieved 2010-10-01. 
5. ^ "Formatting Text - Diasporial". http://diasporial.com/tutorials/formatting-text. Retrieved 2011-11-09. 
6. ^ "Markdown add-on for Drupal". http://drupal.org/project/markdown. Retrieved 2011-11-15. 
7. ^ "Making GitHub More Open: Git-backed Wikis - GitHub". http://github.com/blog/699-making-github-more-open-git-backed-wikis. Retrieved 2010-09-01. 
8. ^ "GitHub Flavored Markdown - Introduction". http://github.github.com/github-flavored-markdown/. Retrieved 2011-01-03. 
9. ^ "Daring Fireball Linked List: GitHub Flavored Markdown". http://daringfireball.net/linked/2009/10/23/github-flavored-markdown. Retrieved 2011-01-03. 
10. ^ "G+ Tweaks v1.1151". http://userscripts.org/scripts/show/106166. Retrieved 2011-11-08. 
11. ^ "Markup Choices in Instiki". http://golem.ph.utexas.edu/wiki/instiki/show/Markup+Choices. Retrieved 2010-08-24. 
12. ^ "Markdown - Posterous Help". http://posterous.com/help/markdown. Retrieved 2010-06-26. 
13. ^ "Reddit's help document on Markdown". http://www.reddit.com/help/commenting. Retrieved 2010-07-20. 
14. ^ "Showoff project on GitHub". https://github.com/schacon/showoff. Retrieved 2011-10-24. 
15. ^ "Squarespace Mini-Reference". http://www.squarespace.com/display/ShowHelp?section=Markdown. Retrieved 2010-09-30. 
16. ^ "Markdown Editing Help - Stack Overflow". http://stackoverflow.com/editing-help. Retrieved 2010-04-29. 
17. ^ "Three Markdown Gotchas - Blog – Stack Overflow". http://blog.stackoverflow.com/2008/06/three-markdown-gotcha/. Retrieved 2010-04-29. 
18. ^ "Tumblr Preferences". http://www.tumblr.com/preferences. Retrieved 2011-01-03. 
19. ^ "WordPress Plugins". http://wordpress.org/extend/plugins/about/. Retrieved 2011-02-14. 

External links

• Official Markdown project at Daring Fireball
• Markdown Wiki
• Introduction to Markdown (tutorial)
• Older Markdown Wiki
• MultiMarkdown (Improved Markdown with more syntax-features and export-options than traditional Markdown)

Alternate implementations

• MarkdownSharp, a slightly modified C# implementation of the Markdown markup language. Developed and used by Stack Overflow.
• PHP Markdown
• Discount, a C implementation of the Markdown markup language
• WMD, a Javascript "WYSIWYM" editor for Markdown (from AttackLab)
• uedit, a Javascript "WYSIWYM" editor for Markdown
• Markdownr.com, a simple website to preview markdown in real time
• BlueCloth, an implementation of Markdown in Ruby
• MarkdownPapers, Java implementation based on a JavaCC parser
• pegdown, a pure-Java Markdown implementation based on a PEG parser
• Knockoff, a Markdown implementation written in Scala using Parser Combinators
• Actuarius, another Markdown implementation written in Scala using Parser Combinators
• Pandoc, a universal document converter
• Txtmark, another Markdown implementation written in Java
• Markdown in Python, A Python implementation of Markdown
• Blackfriday, another Markdown implementation written in Go
• Markdown Viewer for PHP, allows viewing the of a Mardown doc via a local PHP server (a wrapper for PHP Markdown)
• MarkdownPad, a full-featured Markdown editor for Windows.