Style guide
Conventions#
Text styles#
Italics is indicated using the underscore _ character: _Italics_.
Bold is indicated using the underscore * character: **Bold**.
This creates a clearer visual distinction between the two when reading raw Markdown.
In-line lists#
In-line lists use the Oxford Comma before the ‘and’ that introduces the final item:
Monday, Tuesday, and Wednesday
Unordered lists#
Unordered lists are indicated using dashes - rather than asteriscs *.
- An unordered list item
- Another one
- An unordered list item
- Another one
Ordered lists#
Ordered lists are indicated using dashes 1. for each item, rather than incremental numbers. This is to improve maintainability by making it easier to reorder items.
1. An ordered list item
1. Another one
- An ordered list item
- Another one
Banners#
Admonitions#
Built-in#
Abstract title
This is an abstract
This is an abstract without title
This is an abstract inline end
Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text.
Example title
This is an example
Example title
This is an example
Info title
This is some info
Info title
This is some info
Note title
This is a note
Note title
This is a note
Question title
This is a question
Question title
This is a question
Tip title
This is a tip
Tips are often used without title, inline end
Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text.
Quote title
This is a quote
Success title
This is a success
Success title
This is a success
Warning title
This is a warning
Warning title
This is a warning
Failure title
This is a failure
Failure title
This is a failure
Custom#
Aside title
This is an aside
Aside title
This is an aside
Aside title (typical usage, pre-collapsed)
This is an aside
Fancy quote title
This is a fancy quote, a custom admonition
Fancy quote title
This is a fancy quote, a custom admonition
Fancy quote title
This is a fancy quote inline end
Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text.
Fancy quote title
This is a fancy quote inline end
Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text.
This is a side-image:
Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text. Some example text.
Not used#
Danger title
This is a danger — this built-in admonition type is not used in this handbook.
Danger title
This is a danger — this built-in admonition type is not used in this handbook.
Bug title
This is a bug — this built-in admonition type is not used in this handbook.
Bug title
This is a bug — this built-in admonition type is not used in this handbook.
Image#
Image title. A longer caption.