Markdown Nested Lists and Indentation Rules
TL;DR
- Create a nested list by indenting child items under a parent item.
- Think in terms of the parent item's content column, not a fixed universal number of spaces.
- In monospaced editors, it is usually easiest to align the child marker under the first character of the parent item's text.
- Too much or too little indentation can turn a sublist into a paragraph continuation or a code block.
What it is
A nested list is a list inside another list item. Markdown uses indentation to decide whether new lines belong to the current list item, a child list, a continuation paragraph, or a code block.
Why it matters
Nested lists are one of the most common places beginners get surprised by Markdown parsing. Learning the indentation logic once saves a lot of trial and error later.
Syntax
1. Parent item
- Child item
- Child item
- Parent bullet
1. Child number
2. Child number
Minimal example
Source
1. First item
- First nested item
- Second nested item
What it does
This renders one ordered-list item containing a nested unordered list.
More examples
Example 1: Nested bullets under a numbered item
1. First list item
- First nested list item
- Second nested list item
2. Second list item
What it does
The nested bullets belong to the first numbered item because they are indented under its content.
Example 2: Continuation paragraph plus nested list
- Parent item
This paragraph still belongs to the same list item.
- Nested item
- Another nested item
What it does
The paragraph and the nested list are both part of the same parent list item.
Example 3: Mixed list types
- Outline
1. First numbered child
2. Second numbered child
What it does
A parent bullet can contain a numbered child list when that child list is indented correctly.
Common pitfalls
- Memorizing one fixed indent rule for every case
- Why it happens: many tutorials oversimplify list nesting
- Fix: align child content under the parent item's content rather than relying on one magic number
- Indenting so far that content becomes code
- Why it happens: four-space indentation has special meaning in Markdown
- Fix: preview nested content and reduce indentation if it turns into a code block
- Losing track of whether a line is a continuation paragraph or a child list
- Why it happens: both depend on indentation relative to the parent item
- Fix: add blank lines deliberately and build the list incrementally
- Changing list marker types at the same level unintentionally
- Why it happens:
-,*,+, and numbered markers all look interchangeable at a glance - Fix: if you want a nested list, indent it; if you change the marker without nesting, you may start a new list
- Why it happens:
Portability and platform notes
- List nesting is core Markdown behavior, but it is also one of the areas where implementations historically diverged.
- CommonMark does not use a fixed universal "four spaces for every sublist" rule; indentation is based on the list marker and the content that follows it.
- GitHub's guidance for monospaced editors is practical: visually align the nested marker below the first character of the parent item's text.
- Task lists are a GFM extension layered on top of list items, so learn ordinary nesting first.
FAQ
How many spaces do I indent a nested list?
There is no one-size-fits-all answer that works as a teaching rule for every case. The safest beginner habit is to indent until the child marker sits under the content of the parent item and then preview the result.
Why did my nested list turn into a code block?
Because your indentation crossed into code-block territory for that context. Reduce the indentation and recheck the preview.
Can I mix numbered and bulleted lists?
Yes. A bullet list can contain a numbered list, and a numbered list can contain a bullet list, as long as the child list is indented as a child of the parent item.
Practice
- Create a numbered list with one nested bullet list and one continuation paragraph inside the first item.
- Rewrite a broken nested list until the child items line up under the parent item's text rather than under the marker.
Related topics
- Lists
- Task lists
- Paragraphs and blank lines
- Code blocks