Markdown Lists: Ordered, Unordered, and Nested

Lists are among the most-used elements in Markdown — from README bullet points to step-by-step numbered instructions. Markdown supports ordered lists, unordered lists, nested lists, and task checklists. Here’s how they all work.

Unordered Lists

Use a hyphen -, asterisk *, or plus sign + as the list marker, followed by a space:

- First item
- Second item
- Third item

All three markers produce the same output. Hyphens are the most widely used and recommended for consistency.

You can mix markers in a document (different sections use different markers), but mixing them within the same list can cause unexpected behavior in some parsers — stick to one per list.

Ordered Lists (Numbered Lists)

Use a number followed by a period and a space:

1. First step
2. Second step
3. Third step

The numbers don’t have to be sequential. Most parsers renumber the list automatically. This is valid Markdown:

1. First item
1. Second item
1. Third item

Renders as 1, 2, 3. You can also start a list at any number:

5. Fifth item
6. Sixth item

Renders starting at 5. This is useful for resuming a list after an interruption.

Nested Lists

Indent items by two or four spaces (or one tab) to create sub-lists:

- Fruit
  - Apple
  - Banana
  - Cherry
- Vegetables
  - Carrot
  - Broccoli

Rendered output:

• Fruit
  • Apple
  • Banana
• Vegetables
  • Carrot

You can nest ordered inside unordered and vice versa:

1. Download the repository
   - Option A: use `git clone`
   - Option B: download ZIP from GitHub
2. Install dependencies
   - Run `npm install`
   - Run `pip install -r requirements.txt`
3. Start the server

Most parsers support multiple levels of nesting. Three levels is usually the practical limit before readability suffers.

Task Lists (Checkboxes)

GitHub Flavored Markdown supports task list items with - [ ] for an open checkbox and - [x] for a checked one:

- [x] Create a new project
- [x] Write the README
- [ ] Add tests
- [ ] Deploy to production

Task lists are widely supported in GitHub, GitLab, Notion, and most modern Markdown editors. They’re useful for project checklists, meeting action items, and feature tracking.

Adding Content Between List Items

To add a paragraph, blockquote, or code block between list items, indent it to align with the list marker:

1. First item

   This paragraph is still part of item 1.
   It's indented to match.

2. Second item

   > A blockquote inside an ordered list item.

3. Third item

code block inside a list item

The indent must align with the text start of the list item (typically 3 spaces for ordered, 2 for unordered).

Continuation Without Extra Elements

A blank line between list items turns them into “loose” list items — each one gets wrapped in a <p> tag in the HTML output, which adds spacing. Tight lists (no blank lines between items) render more compactly.

Tight list:

- Item one
- Item two
- Item three

Loose list (each item in a <p>):

- Item one

- Item two

- Item three

Use tight lists for short bullet points, loose lists when items contain full sentences or multiple lines.

Escaping List Markers

If a line starts with a number-period (like 1986. What a year) and you don’t want it to become a list, escape the period with a backslash:

1986\. What a year it was.

Common Mistakes

Forgetting the space after the marker — - item works, -item does not. The space between the marker and text is required.

Inconsistent indentation — Use the same number of spaces throughout your nested lists. Mixing 2-space and 4-space indentation confuses some parsers.

Interrupting an ordered list — A non-list paragraph between numbered items resets the counter in some parsers. If you need numbered items with content between them, use the indented continuation syntax.

Try It

Create and preview lists in the Markdown Monk editor — paste your list, see it rendered, and export to PDF, DOCX, or HTML with one click.