Markdown

Markdown

Filename extension	.md
Internet media type	text/markdown
Developed by	John Gruber and Aaron Swartz
Initial release	December 17, 2004 (2004-12-17)
Type of format	Markup language
Website	daringfireball.net/projects/markdown/

Markdown is a lightweight markup language, originally created by John Gruber with substantial contributions from 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)”. The language takes many cues from existing conventions for marking up plain text in email. In other words, Markdown is a text-to-HTML conversion tool (for web writers).

Markdown is also a script written by Gruber in the Perl programming language, 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.

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.

Sites such as GitHub, reddit and Stack Overflow use Markdown extensively to facilitate discussion between users.

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.

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

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.

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
    1.1. A subitem, indented with 4 spaces
2. Another item in an enumerated list

Emphasized text

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

**strong emphasis** 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.

Line breaks

When you do want to insert a break tag using Markdown, you end a line with two or more spaces, then type return. For example:

def show_results space space
end

Result:

def show_results
end

You can also use two newlines. For example:

sentence A

sentence B

Result:

sentence A
sentence B

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 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.</p></blockquote>

External links

Links may be included inline:

[link text here](link.address.here)
Ex. [Markdown](http://en.wikipedia.com/wiki/Markdown)

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"

Images

Images have similar syntax to links with a preceding exclamation point.

![Alt text](/path/to/img.jpg)

Or:

![Alt text](/path/to/img.jpg "Optional title")

Like links, images also have a footnote style syntax

![Alt text][id]

with a reference later in the document defining the URL location.

[id]: url/to/image  "Optional title attribute"

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:

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

Editors

While Markdown is a minimal markup language and is easily read and edited with a normal text editor there are special designed editors which preview the files direct with styles. There are a variety of such editors available for all of the major platforms. There are syntax highlighting plugins for markdown built into gedit and vim.

Implementations

Implementations of Markdown are available for many different frameworks, platforms and languages.

• The sourcecode documentation generator Doxygen supports Markdown with extra features.
• RStudio, an IDE for R provides a C++ wrapper function for the markdown implementation sundown.
• IntelliJ IDEA, an IDE for Java, provides a Markdown plugin

There are many more open-source software implementations of Markdown available online.

See also

• List of Markdown implementations
• Comparison of document markup languages
• Comparison of documentation generators
• Markdown extensions
• Org-mode has similar lightweight markup.
• MultiMarkdown, another improved Markdown with more syntax-features and export-options than traditional Markdown.
• reStructuredText, a similar lightweight markup, also used for Python documentation.
• Textile, a similar lightweight markup language to produce HTML.
• AsciiDoc, a similar lightweight markup language supporting many types of documents.
• txt2tags, another lightweight markup language.
• Setext, an old lightweight markup language (1992).

External links

• Official Markdown project at Daring Fireball