How to use lists in Markdown

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

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

Unordered Lists

Unordered lists are used to enumerate items 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 item text.

* Item 1
* Item 2
* Item 3

- Item 1
- Item 2
- Item 3

+ Item 1
+ Item 2
+ Item 3

All the options above render the same way:

Nesting Unordered Lists

You can create nested lists by simply 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 items 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 item text. 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:

Uhh, seriously… don’t do that. It will work, but don’t do it 😉.