Text

Markdown supports a range of standard markup commands to format blocks of content. Here we cover the most commonly used ones.

Headings

In Markdown write # Title to produce a first-level heading, ## Title to produce a second-level heading, etc. You can use 1–6 hash symbols.

Although not necessary, it is good practice to put a blank line before and after each heading, except before first-level headings.

Each file must start with a first-level heading, no matter where the file is in the content and TOC structures.

Check that the page’s heading levels are correct by looking at the rendered page’s outline on the right sidebar.

Paragraphs

Paragraphs are separated by blank lines. To break a line in the middle of a paragraph, put a backslash followed by newline where you
want the break. For example, this paragraph is written

put a backslash followed by newline where you\
want the break. For example, this paragraph is written

Lists

Lists can be ordered (numbered) or unordered (bullet) and can be nested as deep as needed.

Ordered list items are defined by placing the number and a full-stop before the list item. Unordered list items are defined by using a minus - before the list item:

1. first item of numbered list
2. second item of numbered list
   - first item of nested bullet list
     - first item of further nested bullet list
3. third item of numbered list
   1. first item of nested numbered list

The markdown above will produes

1. first item of numbered list

2. second item of numbered list

   • first item of nested bullet list

     • first item of further nested bullet list

3. third item of numbered list

   1. first item of nested numbered list

Put a blank line before and after the top-level list and use spaces to indent nested content, so that it is in line with the first character of the nested text.

You can start an ordered list with any number, by specifying the starting number:

4. This continues the previous list.

This results in the following output:

4. This continues the previous list.

Task lists

You can put a checkbox in front of any list item to produce a list of task items:

1. [x] First task, done
2. [ ] Second task, outstanding
   - [x] completed subtask

This produces

1. First task, done

2. Second task, outstanding

   • completed subtask

Blockquotes

To make one or more paragraphs of text stand out, start each line with >. You can use blockquotes for any purpose, but they are formated for use as quotations:

> Major points to note:
> - No explanation why it's called a blockquote.
> - Grey looks drab. Can we use a different colour?

produces

Major points to note:

• No explanation why it’s called a blockquote.

• Grey looks drab. Can we use a different colour?

Attribution is best attached to the quotation as follows:

{attribution="Fred Brooks, *The Mythical Man-Month*"}
> Adding people to a late project makes it later.

This produces

Adding people to a late project makes it later.

—Fred Brooks, The Mythical Man-Month

Block markup

Blocks are used to mark up blocks of content that belong together semantically. All blocks follow the following basic structure:

:::{block-name}
:::

Importantly at least three colons (:::) must be used before the block name and exactly the same number of colons must be used to mark the end of the block. You can use more colons, the important thing is just to ensure that the same number of colons is used to mark the end of the block.

Some blocks take additional content, such as a title, attributes, and content. If all of these are used, then the resulting structure looks like this:

:::{block-name} Block Title
:attribute: value

Block content
:::

Which of these can be added to a block is documented with the individual blocks.

Blocks can be nested by using additional colons before the block name and at the end of the block.

::::{outer-block} The outer block
:::{inner-block} The inner block
Content in the inner block.
:::
::::

As noted above, the number of colons marking the end of the blocks must exactly match the number of colons before the block name, to ensure that Sphinx can correctly determine the block nesting.

Inline markup

The following standard text markup is available in Markdown:

• **text in bold** to get text in bold,

• *text in italics* to get text in italics,

• ***bold italics*** to get text in bold italics,

• `monospaced text` (note the backticks) to get monospaced text, generally used for inline code,

• -- (two hyphens) produces an em-dash (–).

If the text includes backticks (`), then the text must be separated from the markup backticks using a space and the number of markup backticks must be larger than the number of consecutive backticks in the text…

For example, the text a backtick ` isn't a quote mark has a single backtick in it. To correctly mark that up, you must write `` a backtick ` isn't a quote mark ``.

If the bold or italic text includes asterisks, put a backslah before the text asterisks: **\*important\*** produces *important*.

Roles

The basic markup is extended by a range of default roles, that provide a set of

General typography:

• sub for subscripts: H{sub}`2`O produces H₂O,

• sup for superscripts: 3{sup}`rd` produces 3^rd,

• file to mark text as being a file name: {file}`content/conf.py` produces content/conf.py.

Computer-related:

• kbd to display key combinations: {kbd}`Ctrl+Shift+A` produces Ctrl+Shift+A,

• guilabel to display elements of a graphical or command-line user interface: {guilabel}`File` produces File.