Discourse Meta
Global.anthropic.claude-sonnet-4-5-20250929-v1:0

CommonMark Mixed List Indentation Rules Explained

sam

explain why in commonmark:

  1. one
    • a
  2. two
    • b

there need to be 3 vs 2 spaces in this mixed list I am confused

Researcher_bot

I’ll search for information about CommonMark’s specific indentation rules for mixed lists.

Thinking

Search Google
Found 930 results for ‘CommonMark mixed ordered unordered list indentation spaces rules’

Browse Web
Reading https://commonmark.org/help/tutorial/10-nestedLists.html

Search Google
Found 913 results for ‘CommonMark spec list item indentation content indent calculation’

Browse Web
Reading https://spec.commonmark.org/0.31.2/#list-items

Let me search for a more specific section about list item content indentation:

Thinking

Search Google
Found 15 results for ‘CommonMark list item content indent “3 spaces” ordered unordered marker width’

Let me explain why your mixed list needs different indentation! This is actually one of the more subtle aspects of CommonMark’s list rules.

The Key Concept: Content Indent

In CommonMark, the indentation required for list content depends on the width of the list marker plus the spaces after it. Let me break down your example:

1. one
   - a
2. two
   - b

Why 3 spaces for the nested list?

For the ordered list item "1. ":

  • The marker 1. is 2 characters wide
  • There’s 1 space after it (required minimum)
  • Total: 3 characters before the content starts

So any continuation content (including nested lists) needs to be indented 3 spaces to align with where “one” starts.

For the unordered list item "- ":

  • The marker - is 1 character wide
  • There’s 1 space after it
  • Total: 2 characters

So content under the unordered list items only needs 2 spaces.

The Rule from the Spec

From the CommonMark specification[1]:

“If a sequence of lines Ls constitute a sequence of blocks Bs starting with a character other than a space or tab, and M is a list marker of width W followed by 1 ≤ N ≤ 4 spaces of indentation, then the result of prepending M and the following spaces to the first line of Ls, and indenting subsequent lines of Ls by W + N spaces, is a list item with Bs as its contents.”

In your case:

  • Ordered marker: W=2 (for “1.”), N=1 → requires 3 spaces indentation
  • Unordered marker: W=1 (for “-”), N=1 → requires 2 spaces indentation

Visual Alignment

Think of it as aligning with where the text starts:

1. one    ← text starts at column 4 (after 3 spaces)
   - a    ← indent 3 spaces to align with "one"
2. two
   - b

If you used only 2 spaces for the nested list under an ordered item, it wouldn’t align properly and might not be recognized as nested content.

  1. CommonMark Spec ↩︎