Lists are one of the most practical markdown features. Unordered lists use dashes, asterisks, or plus signs. Ordered lists use numbers followed by a period. You can nest lists to any depth and mix ordered with unordered.

This guide covers the syntax, nesting rules, common pitfalls, and differences across platforms.

Unordered Lists

Use -, *, or + as the bullet marker:

- First item
- Second item
- Third item

All three markers produce the same output. Pick one and stick with it within a document. Dashes (-) are the most common convention.

Do not mix markers in a single list. Some parsers treat different markers as separate lists:

<!-- Might render as two separate lists -->
- Item with dash
* Item with asterisk

<!-- Consistent -->
- Item one
- Item two

Ordered Lists

Use a number followed by a period:

1. First
2. Second
3. Third

The actual numbers do not matter. This renders identically:

1. First
1. Second
1. Third

Using 1. for every item makes reordering easier because you do not have to renumber anything.

You can also start a list at a specific number:

3. Third item
4. Fourth item
5. Fifth item

The list starts at 3 in the rendered output. This is useful when you need to continue a list after a paragraph or code block.

Nested Lists

Indent by two or four spaces (depending on the parser) to nest a list:

- Parent item
  - Child item
  - Another child
    - Grandchild item
- Back to parent level

For ordered lists inside unordered:

- Requirements
  1. Node.js 18 or later
  2. pnpm installed
  3. A GitHub account
- Optional tools
  1. VS Code
  2. Docker

And unordered inside ordered:

1. Set up the project
   - Clone the repo
   - Install dependencies
2. Configure the environment
   - Create `.env` file
   - Add database URL

Indentation Rules

Different parsers require different indentation depths:

Parser	Indentation for Nesting
CommonMark	1-3 spaces (same marker column)
GitHub (GFM)	2 spaces minimum
Obsidian	2 or 4 spaces
VS Code Preview	2 or 4 spaces
MDtoLink	2 spaces minimum

The safest approach: use 2 spaces for unordered lists and 3 spaces for ordered lists (to align with the text after 1. ).

List Continuation

You can add paragraphs, code blocks, and other elements inside a list item by indenting them to match the item’s text:

1. First step

   This paragraph continues the first step. Note the blank line
   above and the 3-space indent matching the text start.

2. Second step

   ```bash
   npm install mdtolink

This code block belongs to step 2.

The blank line before the continued content is required. Without it, some parsers treat it as a new paragraph outside the list.

## Task Lists (Checklists)

GFM adds checkbox syntax for task lists:

```markdown
- [x] Write the draft
- [x] Add screenshots
- [ ] Review with the team
- [ ] Publish

Task lists render as interactive checkboxes on GitHub (in issues and pull requests). On other platforms they appear as static checkboxes. For more on checklists, see the markdown task lists guide.

Definition Lists

Definition lists are not part of standard markdown or GFM, but some processors support them (Pandoc, PHP Markdown Extra, Kramdown):

Term
: Definition of the term

Another term
: Its definition

Since support is inconsistent, most people avoid definition lists in markdown and use a bold term followed by a description instead:

**Term:** Definition of the term.

Platform Differences

Feature	GitHub	VS Code	Obsidian	MDtoLink	CommonMark
Unordered (`-`, `*`, `+`)	Yes	Yes	Yes	Yes	Yes
Ordered (`1.`)	Yes	Yes	Yes	Yes	Yes
Nested lists	Yes	Yes	Yes	Yes	Yes
Task lists (`- [x]`)	Yes	Yes	Yes	Yes	GFM extension
Interactive checkboxes	In issues/PRs	No	Yes	No	No
Definition lists	No	No	No	No	No (parser-dependent)
List start number matters	Yes	Yes	Yes	Yes	Yes
Loose vs tight lists	Yes	Yes	Yes	Yes	Yes

Loose vs Tight Lists

A “tight” list has no blank lines between items. A “loose” list has blank lines:

<!-- Tight: items wrapped in <li> only -->
- Item one
- Item two

<!-- Loose: items wrapped in <li><p> -->
- Item one

- Item two

Loose lists add extra vertical spacing in the output. Most of the time you want tight lists for compact presentation.

Common Mistakes

Wrong indentation. If your nested list does not render, check the indent level. Two spaces is the minimum on most platforms:

<!-- Wrong: only one space -->
- Parent
 - Not nested on GitHub

<!-- Correct: two spaces -->
- Parent
  - Properly nested

Forgetting the blank line before a list. Some parsers need a blank line between a paragraph and a list:

<!-- May not render as a list -->
Here is a list:
- Item one
- Item two

<!-- Safe: blank line before the list -->
Here is a list:

- Item one
- Item two

Breaking a list with a non-indented line. A paragraph at the base indent level ends the list:

1. First item
2. Second item
This line breaks the list.
3. This starts a new list at 3.

Copy-Paste Templates

Basic bullet list:

- Item one
- Item two
- Item three

Numbered list:

1. First
2. Second
3. Third

Nested list:

- Category A
  - Sub-item 1
  - Sub-item 2
- Category B
  - Sub-item 3

Task list:

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

List with continuation:

1. Step one

   Additional details about step one.

2. Step two

   ```bash
   example command

## FAQ

### How do I create a bullet list in markdown?

Start each line with a dash, asterisk, or plus sign followed by a space: `- Item`. Dashes are the most common convention. Add a blank line before the list to be safe across all parsers.

### How do I create a numbered list in markdown?

Start each line with a number, a period, and a space: `1. Item`. The numbers do not need to be sequential. Using `1.` for every item is valid and makes reordering easier.

### How deep can I nest markdown lists?

There is no formal limit. Most parsers handle 5-6 levels without issues. In practice, nesting beyond 3 levels makes content hard to read. Consider restructuring into separate sections or using headings instead.

### Why does my nested list not render correctly?

Check your indentation. Most GFM parsers need at least 2 spaces for nesting. For ordered lists, align the nested content with the text after the number (3 spaces for single-digit numbers). A missing blank line before the list can also cause issues.

## Try It Out

Build your lists with live preview in the [MDtoLink editor](/editor). When your document is ready, publish it to a shareable URL.

See the full syntax in the [markdown cheat sheet](/blog/markdown-cheat-sheet). For blockquote nesting (which follows similar rules), see the [markdown blockquotes guide](/blog/markdown-blockquotes).

Markdown Lists: Ordered, Unordered, and Nested