Introduction

  • Markdown is

    • A plain text formatting syntax

    A software tool, written in Perl, that converts the plain text formatting to HTML.

  • Design goal

    • Its key design goal is readability. Markdown’s formatting syntax is make to be as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

  • Inpiration

    • Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

History

John Gruber created the Markdown language in 2004 in collaboration with Aaron Swartz on the syntax with the goal of enabling people to write using an easy-to-read and easy-to-write plain text format, optionally convert it to structurally valid XHTML (or HTML). Gruber wrote a Perl script, Markdown.pl, which converts marked-up text input to valid, well-formed XHTML or HTML and replaces angle brackets '<' '>' and ampersands '&' with their corresponding character entity references.

Markdown has since been re-implemented in a variety of others programming languages. It is distributed under a BSD-style license and is included with, or available as a plugin for, several content-management systems. Some sites use variants of Markdown to facilitate discussion between users.

Philosophy

Markdown is intended to be as easy-to-read and easy-to-write as is feasible. Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean.

Standardization

Markdown has been characterised by an informal specification and a reference implementation for conversion to HTML. Over time, many Markdown implementations have appeared. People developed these mostly driven by the need for additional features on top of the base syntax—such as tables, footnotes, definition lists (technically HTML description lists), and Markdown inside HTML blocks. The behavior of some of these diverges from the reference implementation. At the same time, a number of ambiguities in the informal specification have attracted attention. These issues spurred an effort by some developers of Markdown parsers for standardisation.

Gruber has argued that complete standardization would be mistaken: "Different sites (and people) have different needs. No one syntax would make all happy."

HTML vs. Markdown

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Implementation

Implementations of Markdown are available for over a dozen programming languages; in addition, many platforms and frameworks support Markdown. Markdown plugins exist for every major blogging platform.

While Markdown is a minimal markup language and is read and edited with a normal text editor, there are specially designed editors that preview the files with styles, which are available for all major platforms. Many general purpose text and code editors have syntax highlighting plugins for Markdown built into them or available as optional download. Editors may feature a side-by-side preview window or render the code directly in a WYSIWYG fashion.

Syntax

Block elements

Paragraphs

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines.

It is done by simply writing the paragraph, without any type of label or punctuation mark. 

	This is paragraph. Aliquam quasi unde aliquid dicta deleniti nihil nemo. Nam consequuntur quis dolorem odio laudantium sequi. Ab dolor ut temporibus ducimus velit et. Recusandae officia dolorem et nostrum velit repudiandae et enim. Excepturi neque velit non.

The rendered output looks like this:

This is paragraph. Aliquam quasi unde aliquid dicta deleniti nihil nemo. Nam consequuntur quis dolorem odio laudantium sequi. Ab dolor ut temporibus ducimus velit et. Recusandae officia dolorem et nostrum velit repudiandae et enim. Excepturi neque velit non.

Line break

When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return. This takes a tad more effort to create a <br />, but a simplistic “every line break is a <br />” rule wouldn’t work for Markdown. 

	This is the first line.
	And this is the second line.

The rendered output looks like this:

This is the first line.
And this is the second line.

Headers

Markdown supports two styles of headers, Setext and atx.

Setext-style headers

They are “underlined” using equal signs (for first-level headers) and dashes (for second-level headers).

	This is an H1
	=============

	This is an H2
	-------------

The rendered output looks like this:

This is an H1

This is an H2

Note: Any number of underlining =’s or -’s will work.

Atx-style headers

They use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. 

	# h1
	## h2
	### h3
	#### h4
	##### h5
	###### h6

The rendered output looks like this:

h1

h2

h3

h4

h5
h6
Note: “Close” atx-style headers ( ## h2 ##) is purely cosmetic. It is the number of opening hashes determines the header level.

Lists

Ordered list use numbers followed by periods:

	1. First item
	2. Second item
	3. Third item

The rendered output looks like this:

  1. First item
  2. Second item
  3. Third item
Note: The actual numbers that are used to mark the list have no effect on the HTML output Markdown produces. The list always will start with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

Unordered list use asterisks, pluses, and hyphens:

	* First item
	* Second item
	* Third item
	+ First item
	+ Second item
	+ Third item
	- First item
	- Second item
	- Third item

The rendered output looks like this:

  • First item
  • Second item
  • Third item

Blockquotes

Markdown uses email-style > characters for blockquoting.

It looks best with a > before every line:

	> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
	> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
	> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
	>
	> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
	> id sem consectetuer libero luctus adipiscing.

The rendered output looks like this:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown allows to put the > before the first line of a hard-wrapped paragraph:

	> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
	consectetuer adipiscing elit.
	Aliquam hendrerit mi posuere lectus.
	Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

	> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
	id sem consectetuer libero luctus adipiscing.

The rendered output looks like this:

     This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

     Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Code block

To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab.


This a normal paragraph

	This is a code block
Note: If you find this inconvenient, try using fenced code blocks

Horizontal rules

To produce a horizontal rule tag (<hr />) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:

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

The rendered output looks like this:

Span elements

Links

To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes.

To create a link, enclose the link text in brackets (e.g., [Duck Duck Go]) and then follow it immediately with the URL in parentheses (e.g., (https://duckduckgo.com)).

	My favorite search engine is [Duck Duck Go](https://duckduckgo.com).

The rendered output looks like this:

My favorite search engine is Duck Duck Go.

Add title

This will appear as a tooltip when the user hovers over the link. To add a title, enclose it in parentheses after the URL.

	My favorite search engine is [Duck Duck Go](https://duckduckgo.com "The best for privacy").

The rendered output looks like this:

My favorite search engine is Duck Duck Go .

Automatic Links

To quickly turn a URL or email address into a link, enclose it in angle brackets.

	<https://duckduckgo.com>
	<fake@example.com>

The rendered output looks like this:

https://duckduckgo.com
fake@example.com

Emphasis

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. Text wrapped with one * or _ will be wrapped with an HTML <em> tag; double *’s or _’s will be wrapped with an HTML <strong> tag.

	*single asterisks*
	_single underscores_
	**double asterisks**
	__double underscores__

The rendered output looks like this:

single asterisks
single underscores
double asterisks
double underscores

Note: Surrounding an * or _ with spaces, it’ll be treated as a literal asterisk or underscore.

Code

To denote a word or phrase as code, enclose it in tick marks (`).

          This is one word with `code`.

The rendered output looks like this:

      This is one word with code.

Note: If the word or phrase you want to denote as code includes one or more tick marks, you can escape it by enclosing the word or phrase in double tick marks (``).

``Use `code` in your Markdown file.``

Images

Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and reference.

Inline image syntax looks like this:

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

That is:

  • An exclamation mark: !;
  • followed by a set of square brackets, containing the alt attribute text for the image;
  • followed by a set of parentheses, containing the URL or path to the image, and an optional title attribute enclosed in double or single quotes.

Reference-style image syntax looks like this:

	![Alt text][id]

Where “id” is the name of a defined image reference. Image references are defined using syntax identical to link references:

	[id]: url/to/image  "Optional title attribute"
Note: Markdown has no syntax for specifying the dimensions of an image; if this is important regular HTML <img> tags can be use.

Backslash escapes

Markdown allows to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax, like this:

	\*literal asterisks\*

The rendered output looks like this:

    *literal asterisks*

Markdown provides backslash escapes for the following characters:

	\   backslash
	`   backtick
	*   asterisk
	_   underscore
	{}  curly braces
	[]  square brackets
	()  parentheses
	#   hash mark
	+   plus sign
	-   minus sign (hyphen)
	.   dot
	!   exclamation mark

Extended syntax

The basic syntax of John Gruber’s original design document added many of the elements needed on a day-to-day basis, but it wasn’t enough for some people. That’s where extended syntax comes in.

Several individuals and organizations took it upon themselves to extend the basic syntax by adding additional elements like tables, code blocks, syntax highlighting, URL auto-linking, and footnotes. These elements can be enabled by using a lightweight markup language that builds upon the basic Markdown syntax, or by adding an extension to a compatible Markdown processor.

Availability

Extended syntax isn’t available in all Markdown applications. You’ll need to check whether or not the lightweight markup language your application is using supports extended syntax. If it doesn’t, it may still be possible to enable extensions in your Markdown processor.

Tables

To add a table, use three or more hyphens (---) to create each column’s header, and use pipes (|) to separate each column. You can optionally add pipes on either end of the table.

	| Country     | Capital     |
	| ----------- | ----------- |
	| Albania     | Tirana      |
	| Bahrain     | Manama      |

The rendered output looks like this:

Country Capital
Albania Tirana
Bahrain Manama

Alignment

Align text in the columns to the left, right, or center by adding a colon (:) to the left, right, or on both side of the hyphens within the header row.

	| Country     | Capital     | Continent     |
	| :---        |    :----:   |          ---: |
	| Albania     | Tirana      | Europe        |

The rendered output looks like this:

Country Capital Continent
Albania Tirana Europe
Bahrain Manama Asia

Fenced code blocks

The basic Markdown syntax allows to create code blocks by indenting lines by four spaces or one tab. Depending on your Markdown processor or editor can be use fenced code blocks., using three tick marks (```) or three tildes (~~~) on the lines before and after the code block. Fenced code blocks do not need to indent any lines.

	```
	{
	"firstName": "Dan",
	"lastName": "Smith",
	"age": 32
	}
	```

The rendered output looks like this:

{
"firstName": "John",
"lastName": "Smith",
"age": 25
}

Footnotes

Footnotes allow you to add notes and references without cluttering the body of the document. When you create a footnote, a superscript number with a link appears where you added the footnote reference. Readers can click the link to jump to the content of the footnote at the bottom of the page.

To create a footnote reference, add a caret and an identifier inside brackets ([^1]). Identifiers can be numbers or words, but they can’t contain spaces or tabs. Identifiers only correlate the footnote reference with the footnote itself — in the output, footnotes are numbered sequentially.

Add the footnote using another caret and number inside brackets with a colon and text ([^1]: My footnote.). You don’t have to put footnotes at the end of the document. You can put them anywhere except inside other elements like lists, block quotes, and tables.

	Here's a simple footnote,[^1] and here's a longer one.[^bignote]
	[^1]: This is the first footnote.
	[^bignote]: Here's one with multiple paragraphs and code.
 	   Indent paragraphs to include them in the footnote.
	    `{ my code }`
	    Add as many paragraphs as you like.

The rendered output looks like this:

Here’s a simple footnote,1 and here’s a longer one.2

1. This is the first footnote. ↩
2. Here’s one with multiple paragraphs and code.
Indent paragraphs to include them in the footnote.
{ my code }
Add as many paragraphs as you like. ↩

Heading IDs

Many Markdown processors support custom IDs for headings — some Markdown processors automatically add them. Adding custom IDs allows you to link directly to headings and modify them with CSS. To add a custom heading ID, enclose the custom ID in curly braces on the same line as the heading.

	### Great Heading {#custom-id}

The HTML looks like this:

      <h3 id="custom-id">Great Heading</h3>

The rendered output looks like this:

Heading IDs

Definition lists

Some Markdown processors allow you to create definition lists of terms and their corresponding definitions. To create a definition list, type the term on the first line. On the next line, type a colon followed by a space and the definition.

	First Term
	: This is the definition of the first term.

	Second Term
	: This is one definition of the second term.
	: This is another definition of the second term.

The rendered output looks like this:

First Term
This is the definition of the first term.
Second Term
This is one definition of the second term.
This is another definition of the second term.

Strikethrough

You can “strikethrough” words by putting a horizontal line through the center of them. The result looks like this. This feature allows you to indicate that certain words are a mistake not meant for inclusion in the document. To strikethrough words, use two tilde symbols (~~) before and after the words.

	~~The world is flat.~~ We now know that the world is round.

The rendered output looks like this:

The world is flat. We now know that the world is round.

Task lists

Task lists allow you to create a list of items with checkboxes. In Markdown applications that support task lists, checkboxes will be displayed next to the content. To create a task list, add dashes (-) and brackets with a space ([ ]) in front of task list items. To select a checkbox, add an x in between the brackets ([x]).

	- [x] Write the press release
	- [ ] Update the website
	- [ ] Contact the media

The rendered output looks like this: