Markdown
3. Block formatting
Block formatting refers to the Markdown formatting capabilities affecting the physical structure of the document as a whole; the canonical example being the paragraph.
Block level elements usually need to be separated by a blank line in order to be separate. This rule is intended to permit manual wrapping of markdown when it may be read without first being processed.
As a result, paragraphs must be separated by a blank line. Without a blank line, both lines would be combined into a single paragraph.
In rare cases you may want to create a manual line break. This can be accomplished by adding two spaces
at the end of a line.
Headings
Headings are created by prefixing a line with a variable number of # characters specifying the level of the heading:
Level 1 Heading
Level 2 Heading
Level 3 Heading
Note that this example is not technically correct due to a behavior where each invocation of the WordPress content filter increases the heading level of the filtered content by one (thus the H1 above is an H3).
Lists
Paragraphs and headings aside, lists are undoubtedly the most commonly used block formatting tool. Bulleted lists are created by prefixing list items with *, -, or + characters.
- Item 1
- Item 2
- Item 3
The format for numbered lists follows naturally. Note that the actual numbers you specify are ignored, so generally you would number all items as 1.. In fact, the numbering style itself will most likely vary depending on the styles imposed by the site:
- Item 1
- Item 2
- Item 3
Markdown lists can be "tight" or "loose" - adding blank lines between list items will cause list items to be treated as paragraphs with additional separation between them:
Item 1
Item 2
Item 3
This brings us to the four space rule, which has several applications in Markdown. You can create a sub-list by indenting it by four spaces from the lower list level:
- 1
- a
- b
- 2
- a
- b
For this reason it can be useful to try and format your lists such that four columns/spaces are allocated to the list marker, otherwise it becomes difficult to determine the required level of indentation. You can also use four spaces to continue a list item in another paragraph:
Item 1, paragraph 1.
Item 1, paragraph 2.
Item 2.
Quotes
A quote or blockquote can be created by prefixing paragraphs or other block-level elements with > characters (as used with email quotations). The quotation will continue until unquoted block level content is encountered. Only the first line and those of subsequent paragraphs need to be marked.
It is essential to realise, at this point, that C and D are, as it were, inseparable. To appoint C alone would have been impossible. Why? Because C, if by himself, would divide the work with A and so assume almost the equal status which has been refused in the first instance to B; a status the more emphasised if C is A's only possible successor.
Images
The syntax for inserting an image is similar to that of a link, only preceded by an exclamation mark. In this case the square brackets can enclose a description or textual alternative to the image, but should be empty if it is not useful (i.e. the image is decorative and unnecessary to understand the content). Images can also use the footnote-style syntax, although it is somewhat less useful in this case.
Images are centered by default and there is no way to wrap text around them.
Tables
Tables can be created using "pipe table" syntax, with each cell separated by a pipe (U+007C VERTICAL LINE) character. The table must start with header and alignment rows:
| City | July High | July Low | January High | January Low |
|---|---|---|---|---|
| Fort Simpson | 24°C | 11°C | -20°C | -29°C |
| Yellowknife | 21°C | 13°C | -22°C | -30°C |
| Inuvik | 20°C | 9°C | -23°C | -31°C |
| Sachs Harbour | 10°C | 3°C | -24°C | -32°C |
This syntax is intentionally awkward and does not support paragraphs - which is fine as tables should only be used for presenting tabular data. If you are having trouble making a table look good, consider whether or not it should be a table in the first place. You don't have to align the cells, but it might make the table easier to edit.
The alignment row follows any column headers, and determines the cell alignment for the entire column according to the position of the : characters:
| Right | Center | Left |
|---|---|---|
| → | ↔ | ← |
| right aligned | center aligned | left aligned |
Definition lists
Definition lists are a special class of list supported by some Markdown dialects which associate one or more definitions with a list of terms. Each definition must appear on its own line, and each term is preceded by a colon (:) in the same way as other Markdown list varieties. There is no such thing as a "tight" definition list - a blank line must appear between terms.
- Apple
- Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
- An American computer company.
- Orange
- The fruit of an evergreen tree of the genus Citrus.