Block Elements

Paragraphs are implicit. Semantic block elements are created with leading block declarations. Arbitrary nesting is possible with indentation.

Notes

Paragraphs are implicit and are delimited by blank lines.
Block elements (except paragraphs) start with block declarations on a separate line. Block declarations start with a square bracket followed by the element name.
Block declarations can contain attribute lists.
Block elements can be nested as deep as necessary using indentation.
Without indentation, block elements usually contain just the following block element, which may be an implicit paragraph. Some block elements, such as lists and tables, have special rules to contain more elements without indentation.
There is a shorthand notation for block titles, list items, and table cells.

Examples

Write two paragraphs without any special syntax:

This is a paragraph.

This is another paragraph.

<p>This is a paragraph.</p>

<p>This is another paragraph.</p>

Use a block declaration to create a note:

[note]
This is a paragraph in a note.

<note>
  <p>This is a paragraph in a note.</p>
</note>

Use indentation to put multiple paragraphs in a note:

[note]
  This is a paragraph in a note.

  This is another paragraph in a note.

<note>
  <p>This is a paragraph in a note.</p>
  <p>This is another paragraph in a note.</p>
</note>

Specification

A block element starts with a block declaration (except for several shorthand cases, which are described below). A block declaration begins an indented line with a left square bracket ([) and a name, followed by either a right square bracket (]) or whitespace. If whitespace follows the block name, an attribute list is opened, and the block declaration continues until it is closed, possibly spanning multiple lines. There must not be any non-whitespace content on the line that follows the end of the block declaration.

The line following the block declarataion defines that block element's inner indent. If that line is blank or indented less than the outer indent of the block element, the block element is empty. If a block element has an inner indent greater than its outer indent, the block element continues consuming child content as long as non-blank lines are indented to at least that level.

If a block element has an inner indent equal to its outer indent, the block element consumes child content according to the following rules:

Starter content refers to an info segment, a title element, a desc element, and a cite element. It can be consumed as described in subsequent cases.
If the block element is a list, steps, terms or tree element, it can consume starter content and then all elements at the same indent level as long as they are item elements. Note that the item elements themselves may consume same-level child content. Blank lines do not affect this case.
If the block element is a tree item, it consumes all elements at the same indent level as long as they are item elements. Note that tree items cannot take block content, so any block content at the inner indent level of a tree item must break out of the entire tree. This includes implicit paragraphs created for normal text or fences after there have already been child tree items.
If the block element is a table element, it can consume starter content and then all elements at the same indent level as long as they are thead, tfoot, tbody, or tr elements. Note that these elements may themselves consume same-level child content. Blank lines do not affect this case.
If the block element is a thead, tfoot, or tbody element, it can consume starter content and then all elements at the same indent level as long as they are tr elements. Note that the tr elements may themselves consume same-level child content. Blank lines do not affect this case.
If the block element is a tr element, it can consume starter content and then all elements at the same indent level as long as they are th or td elements. Note that these elements may themselves consume same-level child content. Blank lines do not affect this case.
Otherwise, the element can consume starter content followed by a maximum of one block element at the same level. A blank line always breaks out of the block element in this case.

If the indented line is normal text content or a fence and the current block element is not a leaf element, an external element, or a tree item without child items, then a Mallard p element is implicitly created with its outer and inner indent set to the indentation of the line.

Leaf elements, external elements, and tree items that do not yet have child items can consume normal text and fenced blocks. For these elements, if the inner indent is the same as the outer indent, they consume normal text and fences, as long as they are at the indent level, until a newline is encountered. If the inner indent is greater than the outer indent, the same rule applies except inside verbatim elements, which consume the newline. Note that newlines in fences do not break out of elements.