Nested Lists in Markdown: Indentation Rules That Work

Quick answer

A nested list works when its marker lines up with the first character of text after the parent item's marker. Not when you've counted a fixed number of spaces — that's the part most people get wrong. A dash marker (- ) only needs 2 spaces of indent for its sublist to nest correctly. A numbered marker like 10) needs 4-5. Get the alignment wrong and the parser treats your sublist as a new, unrelated paragraph instead of a child of the item above it.

- Parent item
  - Nested item (2 spaces — aligns with "P")

10. Parent item
    - Nested item (4 spaces — aligns with "P")

The rest of this guide covers the alignment rule and the marker-width math, the places nesting quietly fails, and how to put a code block or blockquote inside a list item without breaking the structure.

Step-by-step

The real rule: align, don't count spaces

Most people carry over an instinct from other tools: "indent nested lists by 4 spaces." That's the original rule from John Gruber's Markdown.pl, where every level of nesting — sublist or continuation paragraph — takes a flat 4-space or one-tab indent.

CommonMark and GitHub Flavored Markdown (GFM) work differently. A sublist must be indented to align with the first non-whitespace character following the parent list marker, so the required indent isn't fixed — it depends on how wide the parent marker is. The GFM spec puts it plainly: "the position of the text after the list marker determines how much indentation is needed in subsequent blocks in the list item."

Doing the marker-width math

Work out the indent by counting the characters in the parent marker plus its trailing space:

| Parent marker | Characters before text | Sublist indent needed | |---|---|---| | - | 2 | 2 spaces | | * | 2 | 2 spaces | | 9. | 3 | 3 spaces | | 10. | 4 | 4 spaces | | 100. | 5 | 5 spaces |

GitHub's own docs put this in plain terms: to nest a list item under 100. First list item, indent the child a minimum of five spaces — the same number of characters that precede "First" in the parent line. One space short, and the nested marker no longer reads as a child of that item.

Don't want to do the math by hand? Most Markdown-aware editors handle it for you. Place the cursor on the nested line, use Tab to indent and Shift+Tab to outdent, and the editor lines the marker up correctly.

Nesting ordered inside unordered (and vice versa)

The same alignment rule applies no matter which list type sits on which side. You can nest an ordered list under a bullet item, or a bullet sublist under a numbered item:

- Ingredients
  1. Flour
  2. Water
  3. Salt

1. Steps
   - Preheat the oven
   - Mix the dry ingredients

In both cases, the child marker aligns with the first character of the parent item's text — - needs 2 spaces, 1. needs 3.

Common problems and fixes

Why a nested list silently becomes a separate paragraph

This is the most common failure. Indent a sublist by one space too few, and instead of an error, the parser just renders it as a new top-level paragraph or a fresh list, disconnected from the parent item. There's no warning. The Markdown looks nested in your editor if it's not using a fixed-width font, but the underlying character count is wrong.

The fix is always the same: count the parent marker's characters, trailing space included, and match that exact number of spaces on the child line.

Parsers disagree — Markdown.pl vs CommonMark vs GFM

If a nested list renders correctly on one platform and breaks on another, the cause is usually a difference in which rule the parser follows. Daring Fireball's original spec uses the flat 4-space convention; CommonMark-based parsers, including GFM, use the marker-alignment rule instead. A 2-space nested bullet is valid under GFM but may not render as nested under an older, Markdown.pl-based parser expecting 4 spaces. When you're not sure which parser will render your file, marker-alignment is the safer default — it's what CommonMark, GFM, and most modern renderers implement.

Putting code blocks and blockquotes inside a list item

Nesting other block types inside a list item takes one more level of indentation than a plain sublist:

- Parent item

  ```
  code fenced inside the list item, aligned with the parent text
  ```

  > A blockquote nested inside the same item,
  > with its `>` aligned to the parent text.

The list, code fence, and blockquote all need to align with the first character of "Parent item" above them. Drop that alignment and the code block or quote gets read as separate content instead of part of the list item. For a closer look at nesting blockquotes inside a list — including where callouts break the same way — see the companion guide.

Catching this before it ships

Broken nesting doesn't throw an error, which makes it easy to ship a document where a sublist quietly renders flat. If you write a lot of Markdown, running your files through a linter that catches indentation issues before publishing catches this class of mistake automatically, instead of relying on a visual read-through.

Frequently Asked Questions

How many spaces do I need to indent a nested list in Markdown?

It depends on the parent marker's width, not a fixed number. For a dash or asterisk marker (- ), 2 spaces is enough. For a numbered marker like 10) or 100., you need 4-5 spaces. The real rule is: align the nested marker with the first character of text after the parent marker.

Why does my nested list break in some editors but not others?

Markdown has no single standard. The original Markdown.pl uses a flat 4-space rule for any nesting. CommonMark and GitHub Flavored Markdown instead require alignment with the first non-space character after the parent marker. A 2-space indent that works under GFM can silently fail under a stricter or older parser.

Can I nest an ordered list inside a bullet list (or vice versa)?

Yes. Mixed nesting is fully supported — indent the child list (ordered or unordered) to align with the first character of the parent item's text, following the same alignment rule regardless of marker type.

How do I put a code block or blockquote inside a list item?

Indent it one level further than the list item's own content. An indented code block typically needs 4 extra spaces (8 total from the margin); a fenced code block just needs to align with the item's text. A blockquote needs its > indented to match.

Doing this with Carets

Getting nested-list indentation right is easier when you can actually see the spaces you're typing. Carets is a native Markdown, plain text, and code editor for iPhone, iPad, and Mac — your files stay plain text, so what you see in the editor is exactly what ships, with no hidden auto-formatting rewriting your indentation behind the scenes.

Carets treats Markdown and code the same way, so the same syntax highlighting that helps you spot a stray character in a code file also makes marker alignment easy to check in a long nested list. And with files, projects, and tags to organize your notes, a reference doc like this one — or your own indentation cheat sheet — stays easy to find the next time a nested list refuses to render.

Get Carets on the App Store for iPhone, iPad, and Mac.