Markdown lists

Lists look simple, and flat lists are. Most problems come from nesting, where the number of spaces decides what you get. This page follows the CommonMark rules, which GitHub Flavored Markdown (GFM) shares.

Unordered lists

Start each line with -, * or +, then a space.

- Flour
- Eggs
- Milk

Result:

• Flour
• Eggs
• Milk

All three characters give the same bullets. Pick one and keep it. If you change the character, Markdown starts a new list.

Ordered lists

Start each line with a number, then . or ), then a space.

1. Mix
2. Rest
3. Bake

Result:

1. Mix
2. Rest
3. Bake

How numbering works

Only the first number counts. It sets where the list starts. After that the renderer counts on by itself.

4. Fourth step
4. Fifth step
9. Sixth step

Result:

4. Fourth step
5. Fifth step
6. Sixth step

This means you can number every item 1. and never renumber after an edit. Correct numbers are easier to read in the source, though.

Two more rules:

• A number can have up to nine digits.
• A numbered list that directly follows a paragraph, with no blank line between, must start with 1. Any other start number needs a blank line before the list.

Nesting

To nest a list, indent it so that its marker lines up with the text of the parent item.

• Under - the text starts after two characters, so indent by two spaces.
• Under 1. the text starts after three characters, so indent by three spaces.
• Under 10. it is four spaces.

One to three spaces more than that also work. Fewer do not.

- Fruit
  - Apples
  - Pears
- Vegetables

1. Prepare
   - Wash
   - Peel
2. Cook

Result:

• Fruit
  • Apples
  • Pears
• Vegetables

1. Prepare
   • Wash
   • Peel
2. Cook

What goes wrong

Two spaces are not enough under a numbered item. The bullets below are not nested. They form a new list after the first item.

1. Prepare
  - Wash
  - Peel

Result:

1. Prepare

• Wash
• Peel

Four spaces work under both - and 1. . That is a safe habit if you do not want to think about columns.

More than one paragraph in an item

The same rule applies to everything that belongs to a list item. Indent the next paragraph, or a code block, to the start of the item’s text, and leave a blank line before it.

1. Install the tool.

   It needs about a minute.

   ```sh
   brew install example
   ```

2. Run it.

Result:

1. Install the tool.

   It needs about a minute.

   brew install example

2. Run it.

Tight and loose lists

A blank line between items makes the list “loose”. Each item is then wrapped in a paragraph, and most apps show more space between the items. A list without blank lines is “tight”. One blank line anywhere between items makes the whole list loose.

Mixing list types

You can nest an ordered list in an unordered one and the other way round. Each level follows the indentation rule above.

- Before you start
  1. Read the manual
  2. Check the parts
- After you finish

Result:

• Before you start
  1. Read the manual
  2. Check the parts
• After you finish

You cannot mix types on the same level. A bullet after a numbered item, at the same indentation, ends the numbered list and starts a bullet list. The same happens when you switch from - to *, or from 1. to 1).

Where it works

Everything on this page is CommonMark. GFM uses the same list rules and adds task lists on top. GitHub, GitLab and the VS Code preview follow these rules.

Older Markdown tools used a fixed four-space rule for nesting, and some apps still behave that way. If two- or three-space nesting does not work in Obsidian or another app, try four spaces or a tab and check your app.

To check how a nested list comes out, Markko shows .md files formatted on a Mac and in Quick Look.

FAQ

Related