# Block quotations

This is a block quote. This paragraph has two lines.

1. This is a list inside a block quote.
2. Second item.

A “lazy” form, which requires the > character only on the first line of each block, is also allowed:

This is a block quote. This paragraph has two lines.

1. This is a list inside a block quote.
2. Second item.

Among the block elements that can be contained in a block quote are other block quotes. That is, block quotes can be nested:

This is a block quote.

A block quote within a block quote.

# Fenced code blocks

Extension: backtick_code_blocks

# Line blocks

Extension: line_blocks

A line block is a sequence of lines beginning with a vertical bar (|) followed by a space. The division into lines will be preserved in the output, as will any leading spaces; otherwise, the lines will be formatted as Markdown. This is useful for verse and addresses:

The limerick packs laughs anatomical
In space that is quite economical.
But the good ones I've seen
So seldom are clean
And the clean ones so seldom are comical

200 Main St.
Berkeley, CA 94718

The lines can be hard-wrapped if needed, but the continuation line must begin with a space.

The Right Honorable Most Venerable and Righteous Samuel L. Constable, Jr.
200 Main St.
Berkeley, CA 94718

This syntax is borrowed from reStructuredText.

# Lists

## Bullet lists

A bullet list is a list of bulleted list items. A bulleted list item begins with a bullet (*, +, or -). Here is a simple example:

• one
• two
• three

This will produce a “compact” list. If you want a “loose” list, in which each item is formatted as a paragraph, put spaces between the items:

• one

• two

• three

The bullets need not be flush with the left margin; they may be indented one, two, or three spaces. The bullet must be followed by whitespace.

List items look best if subsequent lines are flush with the first line (after the bullet):

• here is my first list item.
• and my second.

But Markdown also allows a “lazy” format:

• here is my first list item.
• and my second.

### Block content in list items

A list item may contain multiple paragraphs and other block-level content. However, subsequent paragraphs must be preceded by a blank line and indented to line up with the first non-space content after the list marker.

• First paragraph.

Continued.

• Second paragraph. With a code block, which must be indented eight spaces:

Exception: if the list marker is followed by an indented code block, which must begin 5 spaces after the list marker, then subsequent paragraphs must begin two columns after the last character of the list marker:

• continuation paragraph

List items may include other lists. In this case the preceding blank line is optional. The nested list must be indented to line up with the first non-space character after the list marker of the containing list item.

• fruits
• apples
• macintosh
• red delicious
• pears
• peaches
• vegetables
• broccoli
• chard

As noted above, Markdown allows you to write list items “lazily,” instead of indenting continuation lines. However, if there are multiple paragraphs or other blocks in a list item, the first line of each must be indented.

• A lazy, lazy, list item.

• Another one; this looks bad but is legal.

Second paragraph of second list item.

## Ordered lists

Ordered lists work just like bulleted lists, except that the items begin with enumerators rather than bullets.

In standard Markdown, enumerators are decimal numbers followed by a period and a space. The numbers themselves are ignored, so there is no difference between this list:

1. one
2. two
3. three

and this one:

1. one
2. two
3. three

Extension: fancy_lists

Unlike standard Markdown, pandoc allows ordered list items to be marked with uppercase and lowercase letters and roman numerals, in addition to Arabic numerals. List markers may be enclosed in parentheses or followed by a single right-parentheses or period. They must be separated from the text that follows by at least one space, and, if the list marker is a capital letter with a period, by at least two spaces.2

The fancy_lists extension also allows ‘#’ to be used as an ordered list marker in place of a numeral:

1. one
2. two

Extension: startnum

Pandoc also pays attention to the type of list marker used, and to the starting number, and both of these are preserved where possible in the output format. Thus, the following yields a list with numbers followed by a single parenthesis, starting with 9, and a sublist with lowercase roman numerals:

1. Ninth
2. Tenth
3. Eleventh
1. subone
2. subtwo
3. subthree

Pandoc will start a new list each time a different type of list marker is used. So, the following will create three lists:

1. Two
2. Three
1. Four
• Five

If default list markers are desired, use #.:

1. one
2. two
3. three

## Definition lists

Extension: definition_lists Pandoc supports definition lists, using the syntax of PHP Markdown Extra with some extensions.3

Term 1

Definition 1

Term 2 with inline markup

Definition 2

Third paragraph of definition 2.

Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions. A definition begins with a colon or tilde, which may be indented one or two spaces.

A term may have multiple definitions, and each definition may consist of one or more block elements (paragraph, code block, list, etc.), each indented four spaces or one tab stop. The body of the definition (including the first line, aside from the colon or tilde) should be indented four spaces. However, as with other Markdown lists, you can “lazily” omit indentation except at the beginning of a paragraph or other block element:

Term 1

Definition with lazy continuation.

Second paragraph of the definition.

If you leave space before the definition (as in the example above), the text of the definition will be treated as a paragraph. In some output formats, this will mean greater spacing between term/definition pairs. For a more compact definition list, omit the space before the definition:

Term 1
Definition 1
Term 2
Definition 2a
Definition 2b

Note that space between items in a definition list is required. (A variant that loosens this requirement, but disallows “lazy” hard wrapping, can be activated with compact_definition_lists: see Non-pandoc extensions, below.)

## Numbered example lists

Extension: example_lists

The special list marker @ can be used for sequentially numbered examples. The first list item with a @ marker will be numbered ‘1’, the next ‘2’, and so on, throughout the document. The numbered examples need not occur in a single list; each new list using @ will take up where the last stopped. So, for example:

1. My first example will be numbered (1).
2. My second example will be numbered (2).

Explanation of examples.

1. My third example will be numbered (3). Numbered examples can be labeled and referred to elsewhere in the document:

2. This is a good example.

As (4) illustrates, ...

The label can be any string of alphanumeric characters, underscores, or hyphens.

## Compact and loose lists

Pandoc behaves differently from Markdown.pl on some “edge cases” involving lists. Consider this source:

• First
• Second:
• Fee
• Fie
• Foe
• Third

Pandoc transforms this into a “compact list” (with no <p> tags around “First”, “Second”, or “Third”), while Markdown puts <p> tags around “Second” and “Third” (but not “First”), because of the blank space around “Third”. Pandoc follows a simple rule: if the text is followed by a blank line, it is treated as a paragraph. Since “Second” is followed by a list, and not a blank line, it isn’t treated as a paragraph. The fact that the list is followed by a blank line is irrelevant. (Note: Pandoc works this way even when the markdown_strict format is specified. This behavior is consistent with the official Markdown syntax description, even though it is different from that of Markdown.pl.)

## Ending a list

What if you want to put an indented code block after a list?

• item one

• item two

{ my code block }

Trouble! Here pandoc (like other Markdown implementations) will treat { my code block } as the second paragraph of item two, and not as a code block.

To “cut off” the list after item two, you can insert some non-indented content, like an HTML comment, which won’t produce visible output in any format:

• item one
• item two

You can use the same trick if you want two consecutive lists instead of one big list:

1. one
2. two
3. three
1. uno
2. dos
3. tres

# Horizontal rules

A line containing a row of three or more *, -, or _ characters (optionally separated by spaces) produces a horizontal rule:

# Tables

Four kinds of tables may be used. The first three kinds presuppose the use of a fixed-width font, such as Courier. The fourth kind can be used with proportionally spaced fonts, as it does not require lining up columns.

## Extension: table_captions

A caption may optionally be provided with all 4 kinds of tables (as illustrated in the examples below). A caption is a paragraph beginning with the string Table: (or just :), which will be stripped off. It may appear either before or after the table.

## Extension: simple_tables

Simple tables look like this:

Demonstration of simple table syntax.
Right Left Center Default
12 12 12 12
123 123 123 123
1 1 1 1

The headers and table rows must each fit on one line. Column alignments are determined by the position of the header text relative to the dashed line below it:4

If the dashed line is flush with the header text on the right side but extends beyond it on the left, the column is right-aligned.

If the dashed line is flush with the header text on the left side but extends beyond it on the right, the column is left-aligned.

If the dashed line extends beyond the header text on both sides, the column is centered.

If the dashed line is flush with the header text on both sides, the default alignment is used (in most cases, this will be left).

The table must end with a blank line, or a line of dashes followed by a blank line.

The column headers may be omitted, provided a dashed line is used to end the table. For example:

 12 12 12 12 123 123 123 123 1 1 1 1

When headers are omitted, column alignments are determined on the basis of the first line of the table body. So, in the tables above, the columns would be right, left, center, and right aligned, respectively.

## Extension: multiline_tables

Multiline tables allow headers and table rows to span multiple lines of text (but cells that span multiple columns or rows of the table are not supported). Here is an example:

Here's the caption. It, too, may span multiple lines.
Centered Header Default Aligned Right Aligned Left Aligned
First row 12.0 Example of a row that spans multiple lines.
Second row 5.0 Here's another one. Note the blank line between rows.

These work like simple tables, but with the following differences:

They must begin with a row of dashes, before the header text (unless the headers are omitted).

They must end with a row of dashes, then a blank line.

The rows must be separated by blank lines.

In multiline tables, the table parser pays attention to the widths of the columns, and the writers try to reproduce these relative widths in the output. So, if you find that one of the columns is too narrow in the output, try widening it in the Markdown source.

Headers may be omitted in multiline tables as well as simple tables:

 First row 12 Example of a row that spans multiple lines. Second row 5 Here's another one. Note the blank line between rows.

It is possible for a multiline table to have just one row, but the row should be followed by a blank line (and then the row of dashes that ends the table), or the table may be interpreted as a simple table.

## Extension: grid_tables

Grid tables look like this:

Sample grid table.
Bananas $1.34 • built-in wrapper • bright color Oranges$2.10
• cures scurvy
• tasty

The row of =s separates the header from the table body, and can be omitted for a headerless table. The cells of grid tables may contain arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). Cells that span multiple columns or rows are not supported. Grid tables can be created easily using Emacs table mode.

Alignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header:

Right Left Centered

## Small caps

To write small caps, use the smallcaps class:

Small caps

Or, without the bracketed_spans extension:

Small caps

For compatibility with other Markdown flavors, CSS is also supported:

Small caps

This will work in all output formats that support small caps.

# LaTeX macros

Extension: latex_macros


$\langle a, b, c \rangle$

In LaTeX output, the \newcommand definition will simply be passed unchanged to the output.

Markdown allows links to be specified in several ways.

If you enclose a URL or email address in pointy brackets, it will become a link:

An inline link consists of the link text in square brackets, followed by the URL in parentheses. (Optionally, the URL can be followed by a link title, in quotes.)

This is an inline link, and here's one with a title.

There can be no space between the bracketed part and the parenthesized part. The link text can contain formatting (such as emphasis), but the title cannot.

Email addresses in inline links are not autodetected, so they have to be prefixed with mailto:

Write me!

An explicit reference link has two parts, the link itself and the link definition, which may occur elsewhere in the document (either before or after the link).

The link consists of link text in square brackets, followed by a label in square brackets. (There cannot be space between the two unless the spaced_reference_links extension is enabled.) The link definition consists of the bracketed label, followed by a colon and a space, followed by the URL, and optionally (after a space) a link title either in quotes or in parentheses. The label must not be parseable as a citation (assuming the citations extension is enabled): citations take precedence over link labels.

Here are some examples:

The URL may optionally be surrounded by angle brackets:

The title may go on the next line:

Note that link labels are not case sensitive. So, this will work:

In an implicit reference link, the second pair of brackets is empty:

See my website 2.

Note: In Markdown.pl and most other Markdown implementations, reference link definitions cannot occur in nested constructions such as list items or block quotes. Pandoc lifts this arbitrary seeming restriction. So the following is fine in pandoc, though not in most other implementations:

My block quote.

In a shortcut reference link, the second pair of brackets may be omitted entirely:

See my website.

To link to another section of the same document, use the automatically generated identifier (see Header identifiers). For example:

See the Introduction.

or

See the Introduction.

Internal links are currently supported for HTML formats (including HTML slide shows and EPUB), LaTeX, and ConTeXt.

# Images

A link immediately preceded by a ! will be treated as an image. The link text will be used as the image’s alt text:

## Extension: implicit_figures

An image with nonempty alt text, occurring by itself in a paragraph, will be rendered as a figure with a caption. The image’s alt text will be used as the caption.

How this is rendered depends on the output format. Some output formats (e.g. RTF) do not yet support figures. In those formats, you’ll just get an image in a paragraph by itself, with no caption.

If you just want a regular inline image, just make sure it is not the only thing in the paragraph. One way to do this is to insert a nonbreaking space after the image:

Note that in reveal.js slide shows, an image in a paragraph by itself that has the stretch class will fill the screen, and the caption and figure tags will be omitted.

Attributes can be set on links and images:

An inline   and a reference with attributes.

(This syntax is compatible with PHP Markdown Extra when only #id and .class are used.)

For HTML and EPUB, all attributes except width and height (but including srcset and sizes) are passed through as is. The other writers ignore attributes that are not supported by their output format.

The width and height attributes on images are treated specially. When used without a unit, the unit is assumed to be pixels. However, any of the following unit identifiers can be used: px, cm, mm, in, inch and %. There must not be any spaces between the number and the unit. For example:

Dimensions are converted to inches for output in page-based formats like LaTeX. Dimensions are converted to pixels for output in HTML-like formats. Use the --dpi option to specify the number of pixels per inch. The default is 96dpi. The % unit is generally relative to some available space. For example the above example will render to

<img href="file.jpg" style="width: 50%;" /> (HTML),

\includegraphics[width=0.5\textwidth]{file.jpg} (LaTeX), or

\externalfigure[file.jpg][width=0.5\textwidth] (ConTeXt).

, or both (HTML). When no width or height attributes are specified, the fallback is to look at the image resolution and the dpi metadata embedded in the image file.

# Spans

Extension: bracketed_spans

A bracketed sequence of inlines, as one would use to begin a link, will be treated as a span with attributes if it is followed immediately by attributes:

This is some text

# Footnotes

Extension: footnotes

Pandoc’s Markdown allows footnotes, using the following syntax:

Here is a footnote reference,1 and another.2

This paragraph won't be part of the note, because it isn't indented.

The identifiers in footnote references may not contain spaces, tabs, or newlines. These identifiers are used only to correlate the footnote reference with the note itself; in the output, footnotes will be numbered sequentially.

The footnotes themselves need not be placed at the end of the document. They may appear anywhere except inside other block elements (lists, block quotes, tables, etc.). Each footnote should be separated from surrounding content (including other footnotes) by blank lines.

## Extension: inline_notes

Inline footnotes are also allowed (though, unlike regular notes, they cannot contain multiple paragraphs). The syntax is as follows:

Here is an inline note.3 Inline and regular footnotes may be mixed freely.

# Typography

Extension: smart

Interpret straight quotes as curly quotes, --- as em-dashes, -- as en-dashes, and ... as ellipses. Nonbreaking spaces are inserted after certain abbreviations, such as “Mr.” This option currently affects the input formats markdown, commonmark, latex, mediawiki, org, rst, and twiki, and the output formats markdown, latex, and context.

Note: If you are writing Markdown, then the smart extension has the reverse effect: what would have been curly quotes comes out straight.

In LaTeX, smart means to use the standard TeX ligatures for quotation marks (and '' for double quotes, and ' for single quotes) and dashes (-- for en-dash and --- for em-dash). If smart is disabled, then in reading LaTeX pandoc will parse these characters literally. In writing LaTeX, enabling smart tells pandoc to use the ligatures when possible; if smart is disabled pandoc will use unicode quotation mark and dash characters.

1. Here is the footnote.↩︎

2. Here's one with multiple blocks.

Subsequent paragraphs are indented to show that they belong to the previous footnote.

The whole paragraph can be indented, or just the first line. In this way, multi-paragraph footnotes work like multi-paragraph list items.↩︎

3. Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note.↩︎