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.
The four-space rule
A list item may contain multiple paragraphs and other block-level content. However, subsequent paragraphs must be preceded by a blank line and indented four spaces or a tab. The list will look better if the first paragraph is aligned with the rest:
* First paragraph.
Continued.
* Second paragraph. With a code block, which must be indented
eight spaces:
{ code }
List items may include other lists. In this case the preceding blank line is optional. The nested list must be indented four spaces or one tab:
* fruits
+ apples
- macintosh
- red delicious
+ pears
+ peaches
* vegetables
+ brocolli
+ 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.
Note: Although the four-space rule for continuation paragraphs comes from the official markdown syntax guide, the reference implementation, Markdown.pl, does not follow it. So pandoc will give different results than Markdown.pl when authors have indented continuation paragraphs fewer than four spaces.
The markdown syntax guide is not explicit whether the four-space rule applies to all block-level content in a list item; it only mentions paragraphs and code blocks. But it implies that the rule applies to all block-level content (including nested lists), and pandoc interprets it that way.
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:
5. one
7. two
1. three
Pandoc extension.
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.
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:
9) Ninth
10) Tenth
11) Eleventh
i. subone
ii. subtwo
iii. subthree
Pandoc will start a new list each time a different type of list marker is used. So, the following will create three lists:
(2) Two
(5) Three
1. Four
* Five
If default list markers are desired, use #.:
#. one
#. two
#. three
Definition lists
Pandoc extension.
Pandoc supports definition lists, using a syntax inspired by PHP Markdown Extra and reStructuredText:
Term 1
: Definition 1
Term 2 with *inline markup*
: Definition 2
{ some code, part of 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. The body of the definition (including the first line, aside from the colon or tilde) should be indented four 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.
If you leave space after the definition (as in the example above), the blocks of the definitions will be considered paragraphs. In some output formats, this will mean greater spacing between term/definition pairs. For a compact definition list, do not leave space between the definition and the next term:
Term 1
~ Definition 1
Term 2
~ Definition 2a
~ Definition 2b
Numbered example lists
Pandoc extension.
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:
(@) My first example will be numbered (1).
(@) My second example will be numbered (2).
Explanation of examples.
(@) My third example will be numbered (3).
Numbered examples can be labeled and referred to elsewhere in the document:
(@good) This is a good example.
As (@good) 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 --strict option 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
<!-- end of list -->
{ my code block }
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
