A leaf block holds no other block. This page covers section 4 of the CommonMark specification, version 0.31.2; tables, the GFM leaf block, are on the extensions page. In all of these, a line may be indented by up to three spaces without changing what it is; four or more usually makes it indented code instead.
4.1 Thematic breaks
A line of three or more matching -, _ or *
characters, each optionally followed by any number of spaces or tabs, and nothing else.
It becomes a horizontal rule. A thematic break can interrupt a paragraph; note that a
line of - under a paragraph is read as a setext heading underline first.
***
---
_ _ _4.2 ATX headings
An opening sequence of one to six unescaped # characters, then a space,
a tab or the end of the line. The number of # is the heading level. The
content is what follows, with leading and trailing spaces and tabs removed, and is
parsed as inlines.
The heading may end with an optional closing sequence of any number of
unescaped # characters, which must follow a space or tab and may be
followed by spaces or tabs. So # foo# has the content foo#,
since the second # does not follow a space. A heading can interrupt a
paragraph, needs no blank lines around it, and may be empty.
# Level 1
## Level 2 ##
#hashtag is a paragraph4.3 Setext headings
One or more lines of text, followed by a setext heading underline: a
line of any number of = characters (level 1) or - characters
(level 2), which may be indented by up to three spaces and followed by spaces or tabs.
The heading’s content is the text above, which may run to several lines and is parsed
as inlines.
The underline cannot be a lazy continuation line, and the lines above must themselves
be able to form a paragraph, so an indented line followed by --- is
indented code and a thematic break. Link reference definitions at the start of the
lines are taken out first, and a heading is only formed if text remains.
Two lines
of heading
==========4.4 Indented code blocks
One or more indented chunks, lines indented by four or more spaces, separated only by blank lines. The contents are the literal lines with the first four spaces of indentation removed, each with a final line ending. Blank lines before and after the block are not part of it; blank lines between chunks are kept, including any spaces in them beyond the four removed.
An indented code block cannot interrupt a paragraph, so an indented line directly after a paragraph is a continuation of it. There is no language and no info string.
4.5 Fenced code blocks
A code fence is at least three consecutive backticks or tildes, not
mixed. The line opening the block may be indented by up to three spaces, and that much
indentation is removed from each content line where present. The rest of the opening
line, with leading and trailing white space removed, is the info string.
If the fence uses backticks, the info string may not contain backticks, so
``` aa ``` is a paragraph with a code span and not a fence. An info string
after a tilde fence may contain anything, and may use escapes and references.
The first word of the info string is conventionally the language, and appears on the
HTML as class="language-…". The specification itself attaches no meaning to
any of it.
The block ends at a closing fence of the same character, at least as long as the opening one, indented by up to three spaces and followed only by spaces or tabs. A line with anything else after the fence is ordinary content. If no closing fence is found, the block runs to the end of the document or of the enclosing container. A fence can interrupt a paragraph.
~~~~ ruby startline=3
def foo(x)
return 3
end
~~~~ruby startline=3; the language is ruby.4.6 HTML blocks
A group of lines treated as raw HTML and not escaped in the output. The start and end conditions come in seven kinds, tried in this order. A line may begin an HTML block only if it is indented by up to three spaces. Case does not matter for the tag names.
| Type | Start condition (the line begins with) | End condition (the line holds) |
|---|---|---|
| 1 | <pre, <script, <style or <textarea, then a space, a tab, > or the end of the line | </pre>, </script>, </style> or </textarea> (any of them, whichever started it) |
| 2 | <!-- | --> |
| 3 | <? | ?> |
| 4 | <! and an ASCII letter | > |
| 5 | <![CDATA[ | ]]> |
| 6 | < or </ and one of the block names listed below, then a space, a tab, the end of the line, > or /> | The line is followed by a blank line |
| 7 | A complete open tag (not one of the type 1 names) or closing tag, alone on the line apart from spaces and tabs | The line is followed by a blank line |
The 62 block names for type 6:
address, article, aside, base, basefont, blockquote, body, caption, center, col, colgroup, dd, details, dialog, dir, div, dl, dt, fieldset, figcaption, figure, footer, form, frame, frameset, h1, h2, h3, h4, h5, h6, head, header, hr, html, iframe, legend, li, link, main, menu, menuitem, nav, noframes, ol, optgroup, option, p, param, search, section, summary, table, tbody, td, tfoot, th, thead, title, tr, track, ul.
The end condition is tested on the line that starts the block too, so a type 1 to 5 block can open and close on one line. If the end condition is never met, the block runs to the end of the document or container. Types 1 to 6 can interrupt a paragraph; type 7 cannot, since it would otherwise catch ordinary inline tags. The HTML in a block is passed through unchanged, and Markdown is not read inside it, which is why a blank line matters so much in type 6 and 7 blocks.
4.7 Link reference definitions
A definition gives a name to a link destination and an optional title, for use by reference links anywhere in the document, before or after it. It is made of a link label, indented by up to three spaces, then a colon, optional spaces or tabs (including up to one line ending), a link destination, then an optional link title separated from it by spaces or tabs (including up to one line ending), with nothing else on the line. Nothing of it appears in the output.
[Foo Bar]: /url "the title"
See [foo bar] and [the same place][FOO BAR].Labels are compared after Unicode case folding, with their leading and trailing white space removed and internal runs of it reduced to one space. A label must hold at least one character that is not white space, and at most 999 characters. If several definitions share a label, the first one in the document counts. A definition cannot interrupt a paragraph, but it can sit at the start of one, and in a block quote or list item. See Inlines for the forms of destination and title.
4.8 Paragraphs
A run of non-blank lines that cannot be read as anything else. The lines are joined, and leading spaces and tabs are removed from each. The result is parsed as inlines. The first line may be indented by up to three spaces; the others may be indented by any amount, since an indented code block cannot interrupt a paragraph. Final spaces are removed from the paragraph before inline parsing, so they are never a hard line break.
4.9 Blank lines
Blank lines between blocks are ignored, except for the role they play in deciding whether a list is tight or loose. Blank lines at the start or end of the document are ignored too.
In the viewer
Each of these appears as its own node in the structure tree, with its parts named: the opening and closing sequences of a heading, the fences and info string of a code block, and the label, destination and title of a definition. HTML blocks are named by their type, and their text is passed through unchanged in the HTML tab.