Lists in Markdown

Lists are the most-used piece of Markdown after headings, and the one where indentation quietly decides whether you get what you meant. The syntax is a dash or a number; everything interesting happens in the whitespace.

Try nesting an item, renumbering the ordered list, or mixing a paragraph into an item:

- First item
- Second item
  - Nested one level
  - And another
    - Two levels deep
- Third item

1. Step one
1. Step two
1. Step three

Bulleted lists

Start a line with -, * or + followed by a space. All three produce identical output.

Pick one and never change it inside a document: switching markers mid-list is how you accidentally start a second list right underneath the first. - is the most common choice and the easiest to type.

Numbered lists

A number, a period, a space. And here is the thing worth knowing:

1. Wash the rice
1. Add the water
1. Bring it to a boil

That renders as 1, 2, 3. The numbers in the source do not matter — only the first one sets the starting point. Writing 1. on every line means you can reorder, insert and delete steps without renumbering anything by hand. It is the single most useful habit in this whole guide.

If you want a list to start at 5, write 5. on the first item and 1. on the rest.

Nesting

Indent by two spaces to nest under the item above. Some parsers accept four, some accept three; two works everywhere and is what every modern editor produces.

- Fruit
  - Apple
  - Pear
- Vegetables
  - Carrot
    - Nantes
    - Chantenay

You can nest ordered lists under bulleted ones and the other way round — the marker of each level is independent.

Tight lists and loose lists

This one catches everybody. A blank line between items changes the rendering:

- Tight list
- The items sit close together

- Loose list

- Every item becomes its own paragraph

Without blank lines you get a tight list, where each item is bare text. With blank lines you get a loose list, where every item is wrapped in a <p> and the spacing opens up. Both are valid; the mistake is getting one when you wanted the other. If a list suddenly looks too airy, you have a stray blank line in it.

Paragraphs and code inside an item

To put a second paragraph, a code block or a quote inside a list item, indent it to line up with the item’s text — not with its marker:

1. Install the app

   It is free, with no time limit on the free tier.

2. Open a document

   ```
   # My first heading
   ```

3. Export it

The continuation is indented by three spaces here because 1. is three characters wide. Under a - bullet it would be two.

Common mistakes

No blank line before the list. A list that starts immediately after a paragraph gets absorbed into it by many parsers. Leave a blank line above.

Missing the space after the marker. -Item is not a list, it is a paragraph starting with a dash. - Item is a list.

Indenting by one space. One space is not enough to nest; the item stays at the top level. Use two.

Mixing markers. - item followed by * item can start a new list rather than continuing the old one. Stay consistent.

Renumbering by hand. Write 1. everywhere and let the renderer count.

FAQ

How do I create a nested list in Markdown?

Indent the nested item by two spaces relative to its parent, then use a marker as usual. Each additional two spaces adds a level. Some parsers also accept four spaces, but two is understood everywhere.

Why is my Markdown list not rendering?

The two usual causes are a missing space after the marker — -item instead of - item — and a missing blank line between the preceding paragraph and the first list item. Both make the parser read the lines as ordinary text.

Do the numbers in an ordered Markdown list have to be correct?

No. Only the first number matters, and it sets where the list starts. Writing 1. on every line renders as 1, 2, 3 and makes reordering items painless.

What is the difference between a tight and a loose list in Markdown?

A tight list has no blank lines between items and renders each item as bare text. A loose list has blank lines and wraps each item in a paragraph, which adds vertical spacing. The blank lines are the only difference.

Can I put a code block inside a list item?

Yes. Indent the fenced block so it lines up with the item’s text rather than its marker — two spaces under a bullet, three under 1.. Anything indented that far belongs to the item.