How to create lists¶

Note

This page was written in the style of a How-to Guide according to The Diátaxis Framework.

This guide shows how to create a list in your documentation.

There are several types of lists:

unordered lists.
ordered lists.
nested lists.

Note

Lists should be separated from the rest of the text by line breaks.

Unordered lists¶

You can create an unordered list by writing an asterisk * followed by an space and the items on your list:

* Item 1
* Item 2
* Item 3

The output of this would be:

Item 1
Item 2
Item 3

Ordered lists¶

There are several ways to include numbered lists in your documentation. You can use the following numbering methods:

Arabic: 1, 2, 3, 4, …
Lower roman: i, ii, iii, iv, …
Upper roman: I, II, III, IV, …
Lower alpha: a, b, c, d, …
Upper alpha: A, B, C, D, …

And you can present them the following ways:

Followed by a period. E.g., 1.
Surrounded by parentheses. E.g., (a)
parenthesis on the right. E.g., i)

You can pick any of these numbering types and presentations but you have to keep the same ones for the remainder of the list. The output will always be arabic numbers followed by a period. The numbers have to be written in order but don’t have to start with 1. For example, you can write:

b) b
c) c
d) d

And the output is:

Automatic ordering¶

You can make the numbering automatic if you write a hashtag # instead of the number/letter. For example:

(XX) XX
(#) #
(#) #

The output of this list is:

Nested lists¶

You can include a list inside a list if you add a 4-space indentation or bigger to the items in the nested list. The nested lists don’t have to follow the format from the parent list and you can even mix oredered and unordered lists. For example:

#. Item
    i) nested item 1
    #) nested item 2
#. Item
    * nested item
    * nested item
#. Item

The output is:

Item
1. nested item 1
2. nested item 2
Item
- nested item
- nested item
Item