Markdown Markup Languages

References

• CommonMark
• • Common Mark Specification
• GitHub Flavored Markdown Specification
• Markdown Extra
• MultiMardown
• Pandoc Markdown

Common Mark

Markdown is a plain text format for writing structured documents, based on formatting conventions from email and usenet. It was developed in 2004 by John Gruber in collaboration with Aaron Swartz. In the absence of a specification document, which was not provided by John Gruber's canonical description of Markdown syntax, the original Perl code needed to be looked at to understand it. Because there is no unambiguous spec, implementations have diverged considerably over the last 10 years. CommonMark is a proposal for a standard, unambiguous syntax specification for Markdown, along with a suite of comprehensive tests to validate Markdown implementations against this specification.

What distinguishes Markdown from many other lightweight markup syntaxes, which are often easier to write, is its readability.

The overriding design goal for Markdown’s formatting syntax is to make it 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. (https://daringfireball.net/projects/markdown/)

The specification of commonmark attempts to specify Markdown syntax unambiguously. This document describes how Markdown is to be parsed into an abstract syntax tree.

Any sequence of characters is a valid CommonMark document. A character is a Unicode code point. A line is a sequence of zero or more characters other than line feed 0+00A or carriage return 0+00D followed by a line ending or by the end of the file. A line ending is a line feed (U+00A), a carriage return (U+00D) not followed by a line feed, or a carriage return and a following line feed. A line containing no characters, or a line containing only spaces (U+0020) or tabs (U+009) is called a blank line.

Tabs in lines are not expanded to spaces, but in contexts where spaces help to define block structure, tabs behave as if they are replaced by spaces with a tab stop of 4 characters.

Normally the > that begins a block quote may be followed optionally by a space, which is not considered part of the content.

For security reasons, the Unicode character U+0000 must be replaced with the REPLACEMENT CHARACTER (U+FFFD). Any ASCII punctuation character may be backslash escaped. Backslashes before other characters are treated as literal backslashes. Escaped characters are treated as regular characters and do not have their usual Markdown meanings. If a backslash itself is escaped, the following character is not. A backslash at the end of the line is a hard line break. Backslashes don't work in code blocks, code spans, auto links, or raw HTML, but they work in all other contexts.

Valid HTML entity references (<) and numeric character references can be used in place of the corresponding Unicode character, with the following exceptions:

• Entity and character references are not recognized in code blocks and code spans
• Entity and character references cannot stand in place of special characters that define structural elements in CommonMark.

We can think of a document as a sequence of blocks - structural elements like paragraphs, block quotations, lists, headings, rules, and code blocks. Some blocks (like block quotes and list items) contain other blocks; others (like headings and paragraphs) contain inline content - text, links, emphasized text, images, code spans, and so on.

Indicators of block structure always take precedence over indicators of inline structure. This means that the parsing can proceed in two steps:

1. The block structure of the document is discerned
2. Text lines inside paragraphs, headings, and other block constructs can be parsed for inline structure
3. 1. The second step requires information about link reference definitions that will be available only at the end of the first step.

A line consisting of optionally up to three spaces of indentation, followed by a sequence of three or more matching -, _, or * characters, each followed optionally by any number of spaces or tabs, forms a thematic break.

--- 

___

***

<hr> 

<hr> 

<hr>

More than three characters are allowed, spaces and tabs are allowed between the characters, and spaces are tabs are allowed at the end. Thematic breaks do not need blank lines before or after. They can interrupt a paragraph.

An ATX heading consists of a string of characters, parsed as inline content, between an opening of 1-6 unescaped # characters and an optional closing sequence of any number of unescaped # characters. The opening sequence of # characters must be followed by spaces or tabs. Contents are parsed as inlines, learning and trailing spaces or tabs are ignored in parsing inline content, and up to three spaces of indentation are allowed.

# Hello World

## Hello World 2 

### Hello World 3

<h1>Hello World</h1>

<h2>Hello World 2</h2>

<h3>Hello World 3</h3>

A setext heading consists of one or more lines of text, not interrupted by a blank line, of which the first line does not have more than 3 spaces of indentation, followed by a setext heading underline. The lines of text must be such that, were they not followed by the sentext heading underline, they would be interpreted as a paragraph. A setext heading underline is a sequence of = characters or a sequence of - characters, with no more than 3 spaces of indentation and any number of trailing spaces or tabs. The heading is a level 1 heading if = characters are used and a level 2 heading if - characters are used.

Most existing markdown implementations do not allow the text of setext headings to span multiple lines.

Hello World <h1>
====

Hello World 2 <h2>
---

<h1> Hello World &lt;h1&gt;

 
<h2>Hello World &lt;h2&gt;</h2>

An indented code block is composed of one or more indented chunks separated by blank lines. An indented chunk is a sequence of non-blank lines, each preceded by four or more spaces of indentation. The contents of the code block are the literal contents of the lines, including trailing line endings, minus four spaces of indentation. An indented code block has no info string.

a simple
      indented code block

<pre><code>a simple
  indented code block
</code></pre>

A code fence is a sequence of at least three consecutive backtick characters ` or tildes ~. A fenced code block begins with a code fence, preceded by up to three spaces of implementation. The line with the opening code fence may optionally contain some text following the code fence; this is trimmed of leading and trailing spaces or tabs and called the info string. The info string can not contain any backtick characters. The closing code fence must be at least as long as the opening fence. Unclosed code blocks are closed by the end of the document.

An HTML Block is a group of lines that is treated as raw HTML (and will not be escaped in HTML output).

There are several kinds of HTML block, which can be defined by their start and end conditions. The block begins with a line that meets a start condition, and ends with the first subsequent line that meets a matching end condition - or the end of the document.

<table>

  <tr>

    <td>
      Hi
    </td>

  </tr>

</table>

<table>
  <tr>
<pre><code>&lt;td&gt;
  Hi
&lt;/td&gt;
</code></pre>
  </tr>
</table>

A link reference definition consists of a link label optionally preceded by up to three spaces of indentation, followed by a colon :, optionally three spaces or tabs (including the line ending), a link destination, optional spaces or tabs, and a link title, which if present must be separated from the link destination by spaces or tabs.

[foo]: /url "title"
[foo]

   [foo]: 
      /url  
           'the title'  

[foo]

[Foo*bar\]]:my_(url) 'title (with parens)'

[Foo*bar\]]

<p><a href="/url" title="title">foo</a></p>

 
<p><a href="/url" title="the title">foo</a></p>

 
 
<p><a href="my%20url" title="title">Foo bar</a></p>

A sequence of non-blank lines that cannot be interpreted as other kinds of blocks forms a paragraph. The contents of the paragraph are the result of parsing the paragraph's raw content as inlines.

Blank lines between block level elements are ignored, except for the role they play in determining whether a list is tight or loose.

A container block is a block that has other blocks as its contents. There are two kinds of container blocks: blockquotes and list items.

If X is a sequence of blocks, then the resultant of transforming X in such-and-such a way is a container of type Y with these blocks as content.

A block quote marker optionally preceded by up to three spaces of indentation, consists of (a) the character > together with a following list of indentation, or (b) a single character > followed by a space of indentation.

> # Foo
> bar
> baz

<blockquote>
<h1>Foo</h1>
<p>bar
baz</p>
</blockquote>

A list marker is a bullet list marker or an ordered list marker. A bullet list marker is a -, +, or * character. An ordered list marker is a sequence of 1-9 Arabic digits, followed by either a . character or a ) character.

1.  A paragraph
    with two lines.

        indented code

    > A block quote.

<ol>
<li>
<p>A paragraph
with two lines.</p>
<pre><code>indented code
</code></pre>
<blockquote>
<p>A block quote.</p>
</blockquote>
</li>
</ol>

A list is a sequence of one or more list items of the same type. The list items may be separated by any number of blank items. Two list items are of the same type if they begin with a list marker of the same type. A list is an ordered list if its constituent list items begin with ordered list markers, and a bullet list if its constituent list items begin with bullet list markers. A list is loose if any of its constituent list items are separated by blank lines, or if any of its constituent list items directly contain two block-level elements with a blank line between them. Otherwise a list is tight. (The difference in HTML output is that paragraphs in a loose list are wrapped in <p> tags, while paragraphs in a tight list are not.)

Inlines are parsed sequentially from the beginning of the character stream to the end. A backtick string is a string of one or more backtick characters ` that is neither preceded nor followed by a back tick. A code span begins with a backtick string of equal length. The contents of the code span are the characters between these two backtick strings, normalized in some ways.

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.

A delimiter run is either a sequence of one or more * characters that is not preceded or followed by a non-backslash escaped * character, or a sequence of one or more _ characters that is not preceded or followed by a non-backslash escaped _ character.

A link contains link text (the visible text), a link destination (the URI that is the link destination), and optionally a link title. There are two basic kinds of links in Markdown. In inline links the destination and title are given immediately after the link text. In reference links, the destination and title are defined elsewhere in the document. The link text consists of a sequence of zero or more inline elements enclosed by square brackets. An inline link consists of a link text followed immediately by a left parentheses (, an optional link destination, an optional link title, and a right parentheses ).

[link](/uri "title")

<p><a href="/uri" title="title">link</a></p>

There are three kinds of reference links: full, collapsed, and shortcut,

• A full reference link consists of a link text immediately followed by a link label that matches a link reference definition elsewhere in the document.
• A collapsed reference link consists of a link label that matches a link reference definition elsewhere in the document, followed by the string [].
• A shortcut reference link consists of a link label that matches a link reference definition elsewhere in the document and is not followed by [] or a link label.

[foo]: /url1
[foo]: /url "title"
[foo]: /url "title"

<p><a href="/url1">bar</a></p>
<p><a href="/url" title="title">Foo</a></p>
<p><a href="/url" title="title">foo</a></p>

Syntax for images is like the syntax for links, with one difference. Instead of link text, we have an image description.

![foo](/url "title")

<p><img src="/url" alt="foo" title="title" /></p>

Autolinks are absolute URIs and email addresses inside < and >. They are parsed as links, with the URL or email address as the link label.

• A URI autolink consists of <, followed by an absolute URI followed by a >. It is parsed as a link to the URI, with the URI as the link label.
• An absolute URI consists of a scheme followed by a : followed by zero or more characters other than ASCII control characters , < and >. If the URI includes these characters, they must be percent encoded.

<http://foo.bar.baz>

<MAILTO:FOO@BAR.BAZ>

<p><a href="http://foo.bar.baz">http://foo.bar.baz</a></p>

<p><a href="MAILTO:FOO@BAR.BAZ">MAILTO:FOO@BAR.BAZ</a></p>

Text between < and > that looks like an HTML tag is parsed as raw HTML tag and will be rendered in HTML without escaping. Tag and attribute names are not limited to current HTML tags, so custom tags may be used.

GitHub Flavored Markdown

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. 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 in CommonMark Spec are hence known as extensions and highlighted as such.

GFM enables the table extension, where an additional leaf block type is available. A table is an arrangement of data with rows and columns, consisting of a single header row, a delimiter row separating the header from the data, and zero or more data rows. Each row consists of cells containing arbitrary text, in which inlines are parsed, separated by pipes (|). A leading and trailing pipe is also recommended for clarity of reading, and if there's otherwise parsing ambiguity. Spaces between pipes and cell content are trimmed. Block level elements cannot be inserted in a table.

The delimiter row consists of cells whose only content are hyphens - and optionally, a leading or trailing colon :, or both, to indicate left, right, or center alignment respectively.

| foo | bar |
| --- | --- |
| baz | bim |

| abc | defghi |
:-: | -----------:
bar | baz

<table>
<thead>
<tr>
<th>foo</th>
<th>bar</th>
</tr>
</thead>
<tbody>
<tr>
<td>baz</td>
<td>bim</td>
</tr>
</tbody>
</table>

<table>
<thead>
<tr>
<th align="center">abc</th>
<th align="right">defghi</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center">bar</td>
<td align="right">baz</td>
</tr>
</tbody>
</table>

GFM enables the tacklist extension, where an additional processing step is performed on list items. A task list item is a list item where the first block in it is a paragraph which begins with a tack list item marker and at least one whitespace character before any other content. A task list item marker consists of an optional number of spaces, a left bracket [, either a whitespace character or the letter x in either lowercase or uppercase, and then a right bracket ]. When rendered, the task list item marker is replaced with a semantic checkbox element; in an HTML output, this would be an <input type="checkbox" > element.

- [x] foo
  - [ ] bar
  - [x] baz
- [ ] bim

<ul>
<li><input checked="" disabled="" type="checkbox"> foo
<ul>
<li><input disabled="" type="checkbox"> bar</li>
<li><input checked="" disabled="" type="checkbox"> baz</li>
</ul>
</li>
<li><input disabled="" type="checkbox"> bim</li>
</ul>

GFM enables the strikethrough extension, where an additional emphasis type is available. Strikethrough text is any text wrapped in a matching pair of two tildes ~:

~~Hi~~ Hello, ~there~ world!

<p><del>Hi</del> Hello, <del>there</del> world!</p>

GFM enables the autolink extension, where autolinks will be recognized in a greater number of conditions. Autolinks can also be constructed without requiring the use of < and > to delimit them, although they will be recognized under a smaller set of circumstances. The scheme http will be inserted automatically.

Visit www.commonmark.org/help for more information.

<p>Visit <a href="http://www.commonmark.org/help">www.commonmark.org/help</a> for more information.</p>

GFM enables the tagfilter extension, where the HTML tags below will be filtered when rendering HTML output:

Filtering is done by replacing the leading < with the entity <. These tags are chose in particular as they change how HTML is interpreted in a way unique to them.

Markdown Extra

Markdown Extra is an extension to PHP Markdown implementing some features currently not available with the plain Markdown syntax. This document explains the changes and additions to the Markdown syntax implemented by Markdown Extra.

Inline HTML

Markdown has some serious limitation when it comes to block elements. These restrictions have been lifted in Markdown Extra, and replaced by these less restrictive two:

1. The opening tag of a block element must not be indented by more than three spaces. Any tag indented by more than that will be treated as a code block.
2. When the block element is found inside a list, all its content should be indented with the same amount of space as the list item is indented.

Markdown Inside HTML Blocks

Markdown Extra gives you a way to put Markdown-formatted text inside any block-level tag. You do this by adding a markdown attribute to the tag with the value 1:

<div markdown="1">
This is *true* markdown text.
</div>

The markdown attribute will be stripped and <div>'s content will be converted from markdown to HTML. Markdown Extra is smart enough to apply the correct formatting depending on the block element you put the markdown attribute on.

Special Attributes

With Markdown Extra, you can set the id and class attribute of certain elements using an attribute block. You can put the desired id prefixed by a hash inside curly braces after the header, and you can then link back to that header. You can also add multiple class names, attributes and ids inside curly braces:

Header 1            {#header1}
========

[Link back to header 1](#header1)

## Le Site ##    {.main .shine #the-site lang=fr}

At this time, special attribute blocks can be used with:

• headers,
• fenced code blocks,
• links,
• and images

Fenced Code Blocks

Markdown Extra introduced a synax for code block without identation. Fenced code blocks are like Markdown's regular code blocks, except that they're not indented and instead rely on start and end fence lines to delimit code block.

This is a paragraph introducing:

~~~~~~~~~~~~~~~~~~~~~
a one-line code block
~~~~~~~~~~~~~~~~~~~~~

``````````````````
another code block
``````````````````

Tables

Markdown Extra has syntax for simplified tables and regular tables. Additionally, where you put the colon in certain cells of the markdown second row determines the alignment of the cells in that column.

| Item      | Value |
| --------- | -----:|
| Computer  | $1600 |
| Phone     |   $12 |
| Pipe      |    $1 |

Definition Lists

Markdown Extra implements definition lists. Definition lists are made of terms and definitions of these terms, much like in a dictionary. A simple definition list in Markdown Extra is made of a single line-term followed by a colon and the definition for that term. Terms must be separated form previous terms by a blank line. Definitions can span multiple lines, in which case they should be indented.

Apple
:   Pomaceous fruit of plants of the genus Malus in 
    the family Rosaceae.

Orange
:   The fruit of an evergreen tree of the genus Citrus.

Footnotes

Footnotes mostly work like reference-style links. A footnote is made of two things: a marker in the text that will become a superscript number; a footer that will be placed in a list of footnotes at the end of the document. A footnote looks like this:

That's some text with a footnote.[^1]

[^1]: And that's the footnote.

Abbreviations

Markdown Extra adds support for abbreviations. They look like this:

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium

MultiMarkdown

MultiMarkdown, or MMD, is a tool to help turn minimally marked-up plain text into well formatted documents.

MMD is a superset of Markdown syntax. It adds multiple syntax features (tables, footnotes, and citations, to name a few), in addition to various output types.

MultiMarkdown adds the following features to the basic Markdown syntax:

• footnotes
• tables
• citations and bibliography
• math support
• automatic cross-referencing ability
• smart typography, with support for multiple languages
• image attributes
• table and image captions
• definition lists
• glossary entries ( only)
• document metadata (title, author, ...)

Abbreviations

[>MMD]: MultiMarkdown

Citations

This is a statement that should be attributed to
its source[p. 23][#Doe:2006].

And following is the description of the reference to be
used in the bibliography.

[#Doe:2006]: John Doe. *Some Big Fancy Book*.  Vanity Press, 2006.

Inline Citations

As per Doe.[#John Doe. *A Totally Fake Book 1*.  Vanity Press, 2006.]

Deletion

This is {--is --}a test.

Addition

This {++is ++}a test.

Highlighting

This is a {==test==}.

File Transclusion

File Transclusion is the ability to tell MultiMarkdown to insert the contents of another file inside the current file being processed.

This is some text.

{{some_other_file.txt}}

Another paragraph

Superscripts and Subscripts

This apartment has an area of 100m^2. One must consider the value of x~z.
y^(a+b)^
x~y,z~

This apartment has an area of 100m². One must consider the value of x_z. y^(a+b) x_y,z

It is possible to include special metadata at the top of a MultiMarkdown document, such as title, author, etc. This information can then be used to control how MultiMarkdown processes the document:

 Title:    A Sample MultiMarkdown Document  
Author:   Fletcher T. Penney  
Date:     February 9, 2011  
Comment:  This is a comment intended to demonstrate  
          metadata that spans multiple lines, yet  
          is treated as a single value.  
CSS:      http://example.com/standard.css

Math

latex input:	mmd-article-header  
Title:			MultiMarkdown Math Example  
latex input:	mmd-article-begin-doc  
latex footer:	mmd-memoir-footer  
HTML header:	<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

		
An example of math within a paragraph --- \\({e}^{i\pi }+1=0\\)
--- easy enough.

And an equation on it's own:

\\[ {x}_{1,2}=\frac{-b\pm \sqrt{{b}^{2}-4ac}}{2a} \\]

That's it.

Pandoc Markdown

Pandoc understands an extended and slightly revised version of John Gruber's Markdown syntax. Except where noted, the differences between Pandoc Markdown and CommonMark can be suppressed by using the markdown_strict format instead of markdown. An extension can be enabled by adding +EXTENSION to the format name and disabled by adding -EXTENSION., e.g. markdown_strict+footnotes is strict Markdown with footnotes enabled, while markdown-footnotes-pipe_tables is pandoc's Markdown without footnotes or pipe tables.

The header_attributes extension allows for adding header attributes like seen in MultiMarkdown. The extensionauto_identifiers can be used to give a header an unique identifier based on the header text. The extension implicit_header_references can be used to make Pandoc behave as if reference links have been defined for each header:

# Header identifiers in HTML

[the section on header identifiers][header identifiers in
HTML]

The extension fenced_code_blocks gives you fenced code blocks like seen in Markdown Extra.

The fancy_lists extension allows # to be used as an ordered list marker in place of a numeral.

#. one
#. two

The definition_lists extension allows you to insert definition lists like in Markdown Extra.

A caption may be provided with 4 kinds of tables. A caption is a paragraph beginning with the string Table: which will be stripped off. This is enabled by the extension table_captions. The extension simple_tables looks like below:

  Right     Left     Center     Default
-------     ------ ----------   -------
     12     12        12            12
    123     123       123          123
      1     1          1             1

Table:  Demonstration of simple table syntax.

Column Headers may be omitted:

-------     ------ ----------   -------
     12     12        12             12
    123     123       123           123
      1     1          1              1
-------     ------ ----------   -------

The extension multiline_tables allow headers and table rows to span multiple lines of text. The extension grid_tables looks like this:

: Sample grid table.

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

The extension pipe_tables looks like this:

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : Demonstration of pipe table syntax.

The extension pandoc_title_block allows the file to begin with a title block:

% title
% author(s) (separated by semicolons)
% date

You can use the extension strikeout to get strikeout formatting like MultiMarkdown. You can use the extensions superscipt and subscript to get superscripts and subscripts like MultiMarkdown.

You can use the extension tex_math_dollars to treat anything between $ as math. The opening $ must have a non-space character immediately to its right, while the closing $ must have non-space character immediately too its left., and must not be followed immediately as a digit. the way that the math is rendered in HTML depends on the command line option provided to the pandoc command.

• With the --latexmathml option, TeX math will be displayed between $ or $$ characters and put in <span> tags with class LaTeX. The LaTeXMathML script will be used to render it as formulas.
• With the --jsmath option, TeX math will be put inside <span> tags for inline math and <div> tags for display math with class math.

The extension raw_html allows you to insert raw HTML anywhere in a document. The extension markdown_in_html_blocks allows you to include HTML blocks: blocks of HTML between balanced tags separated from the surrounding text with blank lines, and start and end at the left margin. Within these blocks, everything is interpreted as HTML, not Markdown. The extension shortcut_reference_links can be enabled. With the extension link_attributes, attributes can be set on links and images. Pandoc' markdown allows footnotes with the footnotes extension.

• The abbreviations extension can be used to give you Markdown Extra abbreviations.
• The extension mmd_title_block can be used to give you a Multi Markdown like title block.

In addition to pandoc's extended Markdown, the following Markdown variants are supported:

• markdown_phpextra (PHP Markdown Extra)
• • footnotes, pipe_tables, raw_html, markdown_attribute, fenced_code_blocks, definition_lists, intraword_underscores, header_attributes, link_attributes, abbreviations, shortcut_reference_links.
• markdown_github (GitHub-Flavored Markdown)
• • pipe_tables, raw_html, fenced_code_blocks, auto_identifiers, ascii_identifiers, backtick_code_blocks, autolink_bare_uris, intraword_underscores, strikeout, hard_line_breaks, emoji, shortcut_reference_links.
• markdown_mmd (MultiMarkdown)
• • pipe_tables, raw_html, markdown_attribute, mmd_link_attributes, raw_tex, tex_math_double_backslash, intraword_underscores, mmd_title_block, footnotes, definition_lists, all_symbols_escapable, implicit_header_references, auto_identifiers, mmd_header_identifiers, shortcut_reference_links.
• markdown_strict (Markdown.pl)
• • raw_html