.MD File Format – Characters and lines

2.1 Characters and lines

A Markdown document is a sequence of Unicode characters. CommonMark does not fix an encoding, though UTF-8 is normal in practice. Any sequence of characters is a valid document.

A line is a sequence of zero or more characters other than a line feed (U+000A) or carriage return (U+000D), followed by a line ending or by the end of the file. A line ending is a line feed, a carriage return not followed by a line feed, or a carriage return and a line feed together. A line with no characters, or only spaces (U+0020) and tabs (U+0009), is a blank line.

The classes of character the rules below refer to:

2.2 Tabs

Tabs are not expanded to spaces in the text. In the places where whitespace decides the structure, however, a tab behaves as if it were replaced by spaces up to the next tab stop of 4 characters. So a tab can start indented code, and can be partly used: in > foo, the first tab is partly consumed by the block quote’s optional space, and the part left over counts towards the code indentation.

Tabs inside the text of a code block or a line of text are kept as tabs.

2.3 Insecure characters

For security, a NUL character (U+0000) must be replaced by the replacement character (U+FFFD). The same replacement applies to a numeric reference to U+0000.

2.4 Backslash escapes

Any ASCII punctuation character may be backslash-escaped, which makes it a literal character with no special meaning. A backslash before any other character is itself a literal backslash.

\*not emphasis*
\[not a link](/url)
1\. not a list
\# not a heading

Escapes do not work in code blocks, code spans, autolinks or raw HTML, but they do work in link destinations, link titles, and fenced code block info strings. A backslash at the end of a line is a hard line break.

2.5 Entity and numeric character references

Valid HTML entity references and numeric character references stand for the Unicode character they name, anywhere except code blocks, code spans, autolinks and raw HTML. They are recognised, and then treated as literal text rather than as markup, so *foo* is not emphasis.

A numeric reference to an invalid code point, or to U+0000, becomes U+FFFD. Numeric references are not remapped, so € is U+0080 here, not the euro sign an HTML parser would give. The full table of names is part of the HTML Standard.

3.1 Precedence

Block structure is decided before inline structure. So in the example below, the code span cannot span the two list items: the list is settled first, and each line’s backticks are then read within its own item.

- `one
- two`

3.2 Container blocks and leaf blocks

Blocks come in two kinds. Container blocks (block quotes, list items, and lists) hold other blocks. Leaf blocks (thematic breaks, headings, code blocks, HTML blocks, link reference definitions, paragraphs and, in GFM, tables) do not. Most leaf blocks hold inlines; code blocks and HTML blocks hold text taken as it stands.

In the viewer

The viewer on this site keeps the file’s bytes and line endings exactly as they are and traces every construct back to them. Escapes and references appear as their own nodes in the structure tree, each showing what it stands for.