Markdown List Nesting
Last updated: 2026-10-14
List Nesting CommonMark core
A child list indented to the parent item's text start nests: typically 2 spaces under -, 3 under 1.. Nesting is where most list bugs live — one space off and the structure changes.
| Group | Edge Cases & Rules |
|---|---|
| Spec level | CommonMark core |
| Spec version | CommonMark 0.31.2 + GFM |
📝 Syntax
- parent
- child (2 spaces)▶ Live Example
Edit Markdown on the left, see the result on the right
💡 Key points
⚠️ Warning Keep a blank line above a top-level list or some parsers will not see a block.
💡 Tip Mnemonic: count characters after the parent marker — 2 for -, 3 for 1.
❓ FAQ
Q Can unordered nest ordered?
A Yes — indentation decides, marker type does not.
Q How deep can nesting go?
A No hard limit, but past three levels switch to headings.
Q Why is my nesting not working?
A Almost always indentation: too few spaces, mixed tabs, or a missing blank line.
📚 See also
Unordered ListsCommonMark core Ordered ListsCommonMark core Indented Code BlocksCommonMark core