.MD File Format – Container blocks

Markdown

A container block holds other blocks. This page covers section 5 of the CommonMark specification, version 0.31.2. GFM adds task list items, a kind of list item. The container structure is settled before any inline in the document is read.

5.1 Block quotes

A block quote marker is a >, indented by up to three spaces, with an optional following space. Its contents are blocks, and the marker is removed from each line before they are read. There are three ways a line belongs to a quote:

  • It begins with the marker, which is the ordinary case.
  • Laziness. A line of paragraph text may leave the marker out, as long as the text would continue a paragraph inside the quote. Only paragraph text can be lazy.
  • A blank line ends a block quote, so two quotes separated by a blank line are two quotes. A line with only > is a blank line inside the quote, which continues it.
> Quoted paragraph
continues lazily.

> Second quote
> > nested
Two block quotes; the second holds another.

A block quote can interrupt a paragraph. A quote is empty if it has only markers.

5.2 List items

A list marker is either a bullet (-, + or *) or an ordered marker: a sequence of 1 to 9 digits followed by . or ). The digits are the item’s number; they need not be in sequence, and the number may be 0 or have leading zeros. A marker may be indented by up to three spaces.

The rules define a list item’s extent by its contents’ indentation:

  1. Basic case. Let W be the width of the marker with its indentation, and N the number of spaces after it, from 1 to 4. The item’s contents are the following lines, with W + N columns of indentation removed from each. Lines indented less end the item.
  2. Starting with indented code. If the first block in the contents is an indented code block, then N is 1 and the extra indentation stays with the code.
  3. Starting with a blank line. An item may begin with at most one blank line after the marker. Its contents then follow on later lines, indented by W + 1.
  4. Indentation. Up to three spaces of indentation before the marker do not change the item’s structure.
  5. Laziness. As in a block quote, paragraph text may continue without the indentation.
  6. That is all. Nothing that these rules do not make a list item is one.

Since an item’s contents are blocks, it may hold another list, indented to the width of its own contents. An empty list item cannot interrupt a paragraph. An ordered list item may interrupt a paragraph only if its number is 1, so a line such as 14. The number inside a paragraph stays text.

A thematic break wins over a list item: a line such as * * * is a thematic break, not a list.

5.3 Lists

A list is a sequence of one or more list items of the same type: bullet items sharing the same bullet character, or ordered items sharing the same delimiter. Changing the bullet or the delimiter starts a new list. The number of the first item is the list’s start number; the numbers of later items are ignored.

A list is tight if its items and the blocks within them are not separated by blank lines. It is loose if any of its items are separated by blank lines, or if any item directly contains two blocks with a blank line between them. The paragraphs of a tight list are not wrapped in <p> tags; the paragraphs of a loose list are.

- one
- two

1. tight

   and then loose
The first list is tight. In the second, one item holds two blocks with a blank line between them, so it is loose.

Note that this is a rule about what is between items and between the blocks inside them: a blank line after the last item does not make a list loose.

In the viewer

Lists and their items appear in the structure tree with their markers, their type, start number, delimiter and whether they are tight or loose. The markers on the second and later lines of a quote or item show as part of the block that continues there, since the bytes are not contiguous.