How to use lists in Markdown

Lists are an enumeration of elements, and are a fundamental tool for structuring and organizing information in Markdown documents.

Lists can be unordered or ordered. In the former, (guess!) the order of the elements doesn’t matter, while in the latter it does.

Unordered Lists

Unordered lists are used to enumerate elements without a specific order. In Markdown, you can create unordered lists using asterisks (*), hyphens (-), or plus signs (+) at the beginning of each list item.

Syntax

To create an unordered list, simply place an asterisk, hyphen, or plus sign followed by a space and the text of the item.

* Item 1
* Item 2
* Item 3

- Item 1
- Item 2
- Item 3

+ Item 1
+ Item 2
+ Item 3

All the above options render in the same way:

Nesting Unordered Lists

You can create nested lists simply by adding four spaces or a tab before the sublist items.

* Item 1
    * Sub-item 1
    * Sub-item 2
* Item 2
    - Sub-item 1
    - Sub-item 2
* Item 3

This renders as:

Ordered Lists

Ordered lists are ideal for enumerating elements that follow a specific order. In Markdown, you can create ordered lists using numbers followed by a period and a space.

Syntax

To create an ordered list, simply place a number followed by a period and a space before the text of the item. The number you use doesn’t matter, as Markdown will automatically adjust the order when rendering.

1. Item 1
2. Item 2
3. Item 3

This renders as:

Nesting Ordered Lists

Just like with unordered lists, we can create nested ordered lists by adding four spaces or a tab before the sublist items.

1. Item 1
    1. Sub-item 1
    2. Sub-item 2
2. Item 2
    1. Sub-item 1
    2. Sub-item 2
3. Item 3

This renders as:

Mixed Lists

We can also combine unordered and ordered lists in the same document to create a mess that no one understands structure information more effectively.

1. Step 1
    - Detail 1
    - Detail 2
2. Step 2
    - Detail 1
        1. Sub-step 1
        2. Sub-step 2
    - Detail 2
3. Step 3

This renders as:

Eeeh, seriously… don’t do that. It will work for you, but don’t do it 😉.