Nested Task Lists in Markdown: Indentation That Works Across Every Renderer

Quick answer

Four spaces. That's how much you indent a nested task list past its parent item's marker if you want it to render correctly everywhere — GitHub, CommonMark-based parsers, most Markdown editors, Carets included. Two spaces can look fine while you're typing it, then quietly fall apart the moment you switch to an ordered list or open the file in a different renderer. There's no special nesting rule for task lists. They follow the same indentation logic as any other nested list in Markdown.

Why task lists don't have their own nesting rule

A GitHub Flavored Markdown task list isn't a distinct block type. It's a normal list item with [ ] or [x] as the first thing after the marker — the entire extension in one sentence. The GFM spec defines task lists as a checkbox prefix on top of CommonMark's existing list-item grammar, not a new structure with its own rules.

That matters for nesting. A sub-checkbox under a checkbox gets no special treatment; it's parsed exactly like a sublist under a bullet, or a numbered sub-step under a numbered item. GitHub's own tasklists documentation doesn't cover nested indentation at all, because there's nothing task-list-specific to cover. Worth noticing: GitHub's docs actually point people toward native sub-issues for dependent work, rather than deep checkbox nesting inside one Markdown block. Nested task lists are fine for a short to-do inside a single note. They're not a project-tracking structure.

Why 2 spaces sometimes works (and when it breaks)

The formal CommonMark indentation rule for anything nested inside a list item — a sublist, a paragraph, a code block — is marker width plus the spaces after the marker. A bullet marker like - has a width of 1. Add one space before your text and that's 2 spaces total, which is why a bare bullet task list sometimes nests correctly at 2 spaces.

The catch: that rule isn't fixed. Ordered markers change width with the number. 1. needs 3 spaces of continuation indent; 10. needs 4. A flat "just use 2 spaces" habit that worked under a bullet list will silently misalign the moment you switch to numbered steps, or hit a two-digit list. CommonMark's creator has explained why parsers won't special-case a flat 2-space rule — it would break the "Principle of Uniformity," the idea that text means the same thing inside a list item as it does outside one. It would also conflict with how indented code blocks nest inside list items, which already need 4 extra spaces of their own.

The 4-space rule that works everywhere

Four spaces sidesteps all of that. It satisfies the marker-width-plus-spacing rule for bullets, single-digit numbers, and double-digit numbers alike — one width, no per-list-type math. Here's a nested task list built that way:

- [ ] Ship the release notes
    - [ ] Draft the changelog
    - [x] Get sign-off from the team
    - [ ] Post to the changelog page
        - [ ] Cross-post to the support doc
- [x] Tag the release

Each level adds another 4 spaces. Not an arbitrary convention — it traces back to the original Markdown syntax description, which required a list item's continuation paragraphs to be indented 4 spaces or one tab, long before task-list checkboxes existed. CommonMark's own tutorial says it plainly: "indent each item in the sublist by four spaces," and flags it as the safest choice for portability across implementations.

Debugging a nested task list that renders flat

If sub-items show up flat instead of nested, the cause is almost always alignment, not syntax:

• Mixed tabs and spaces. A tab renders differently across editors and parsers. Stick to spaces for list indentation.
• Indent short by one space. Even a 3-space indent where 4 is expected can fall back to "not nested."
• Copy-pasted content. Pasting from another app sometimes strips or collapses leading whitespace. Check the raw Markdown, not just how it looks in a rendered preview.

The fix is the same every time: re-indent every nested line to exactly 4 spaces past the parent marker's start.

Doing this with Carets

Carets is a fast, native notes and code editor for iPhone, iPad, and Mac, built for exactly this kind of Markdown work. It's Markdown, plain text, and code in one editor, so a nested task list you write in Carets is the same portable Markdown you'd commit to a repo, paste into a GitHub issue, or open in another parser. No proprietary checklist format, no lock-in.

It's native and fast, not a web wrapper — checking off a deeply nested to-do list doesn't fight you with lag or reflow. And because your notes live in files, projects, and tags, a running checklist for a release, a trip, or a project can sit right next to the code or notes it belongs to, instead of scattered across a separate task app.

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

Frequently Asked Questions

How many spaces do I need to nest a task list under another task list item?

Four spaces is the portable answer. It satisfies CommonMark's formal indentation rule for every marker type — single-digit, double-digit, and bullet — so a nested task list built with 4 spaces renders correctly in GitHub, CommonMark-based parsers, and most editors. Two spaces sometimes works for a bare bullet marker but breaks under ordered lists or stricter parsers.

Why does 2-space indentation work in some editors but not others?

2 spaces happens to satisfy CommonMark's marker-width-plus-spacing rule for a single-character bullet (-, *, +) followed by one space — that's 2 spaces total. But the same rule requires 3 spaces for a single-digit ordered marker (1.) and 4 for a double-digit one (10.), so a flat 2-space habit silently breaks the moment an ordered list or a different renderer is involved.

Is nesting a task list under a task list different from nesting a plain list?

No. GitHub Flavored Markdown's task list extension only adds the checkbox prefix ([ ] or [x]) to a standard list item — it doesn't define its own nesting behavior. A nested task list follows the exact same indentation rule as a nested plain list or numbered list.

My nested checkboxes render as a flat list instead of nested — what's wrong?

This almost always means the sub-item's indentation doesn't line up with the first character after the parent marker. Check for tabs mixed with spaces, or an indent that's short by even one space — re-indent every nested line to exactly 4 spaces past the parent marker and it will nest correctly.

For task-list syntax basics, see task lists and checkboxes in Markdown. For the general indentation rule this article specializes, see nested lists in Markdown.