Container parsing is where structural intent is most likely to drift across engines.
Lists as container structures
Lists look simple, but they are among the most complex parts of Markdown parsing. A list item is not just a line with a marker. It is a container block that can hold paragraphs, nested lists, block quotes, code blocks, headings, and other content. The list marker opens a structural context, and subsequent lines may continue inside that context depending on indentation and blank lines.
CommonMark supports ordered and unordered lists. Ordered lists use numbers followed by a period or, in CommonMark, a closing parenthesis. For maximum compatibility, periods are safer. Unordered lists use -, +, or *. A production style guide should pick one unordered marker and use it consistently. Mixed markers can create separate lists or confusing source diffs.
The actual numbers in ordered lists are not always rendered exactly as written. Many Markdown renderers output a sequential ordered list. However, the starting number can matter in modern implementations. If you care about source readability, use real numbering. If you care about diff stability, some teams use 1. for every item. Both are valid policies, but the team should choose one.
Tight and loose lists
A tight list renders list items without paragraph wrappers, while a loose list renders items with paragraphs. Blank lines are the main signal that affects tightness. This is not merely visual. It changes the HTML structure and therefore spacing, CSS behavior, and accessibility output.
For short lists, tight formatting is usually appropriate. For list items that contain multiple paragraphs, code blocks, or explanatory text, loose formatting is clearer. The problem arises when a stray blank line changes the entire list’s rendering. This can happen during editing, especially when contributors add examples or nested content.
To keep list behavior predictable, format complex list items deliberately. If an item has multiple blocks, use blank lines and indentation consistently. If an item is simple, avoid unnecessary blank lines. Markdown linters can help detect inconsistent list style.
Nesting and indentation
Nested lists depend on indentation relative to the parent list marker. Many authors memorize “indent by four spaces,” but CommonMark’s actual behavior is more nuanced because the marker width and following spaces affect the content column. Still, a four-space style is a reasonable authoring convention for portability.
The most common mistake is under-indenting nested content. A paragraph intended to belong to a list item may become a paragraph outside the list. A code block intended to appear inside a list may instead close the list or render incorrectly. Fenced code blocks reduce this risk because they are visually explicit, but indentation still matters when they are nested.
When writing tutorials, prefer fenced code blocks inside lists and keep nested structures shallow. Deep nesting is hard to read in source and rendered form. If a list item needs several paragraphs and examples, consider turning it into its own section with a heading.
Blockquotes as containers
Blockquotes use the > marker and can contain other Markdown blocks. This makes them useful for quotations, callouts, warnings, or quoted examples. In CommonMark, blockquotes can contain paragraphs, headings, lists, and code blocks. They can also be nested.
Lazy continuation allows some blockquote paragraphs to continue without repeating > on every line. While this is convenient, it can reduce source clarity. For technical documentation, repeat the > marker on each quoted line. This makes the container visible and avoids confusion during editing.
Because blockquotes are containers, blank lines inside them should usually include the > marker. This keeps the quote visually continuous in source. It also helps prevent accidental termination of the quote in less forgiving parsers.
Lists inside blockquotes and blockquotes inside lists
Container blocks can nest inside each other. A blockquote can contain a list, and a list item can contain a blockquote. The rules are predictable once you think in terms of containers, but they are easy to get wrong visually.
For a blockquote inside a list item, indent the > marker so it belongs to the list item. For a list inside a blockquote, include > before the list marker. In both cases, the source should make ownership obvious. If the structure is hard to read in source, it will be hard to maintain.
This is especially relevant for tutorial content where examples often appear inside steps. A numbered step that contains a warning block, code sample, and explanation can become complex quickly. Sometimes the better documentation design is to break the step into subsections.
Maintenance checklist
When reviewing Markdown lists, check both source readability and rendered output. Confirm that every nested item belongs to the intended parent. Confirm that complex list items still render as a single conceptual item. Confirm that blockquotes include marker lines on blank lines. Confirm that code blocks inside lists use fences where possible. These checks prevent small whitespace edits from changing the document tree.
For collaborative documentation, lists should be optimized for future editors, not only for the original author. If the nesting structure requires careful counting of spaces to understand, simplify it. Markdown is strongest when the source remains self-explanatory.
FAQ
Why do Markdown lists render with different spacing?
Blank lines can make a list loose, which changes paragraph wrapping and spacing in the rendered HTML.
Can list items contain multiple paragraphs?
Yes. A list item is a container block and can contain multiple paragraphs when indentation and blank lines are correct.
Should I use -, *, or + for unordered lists?
Choose one marker for your project and use it consistently. - is a common default for technical documentation.
Why did my nested list break?
The nested item was probably not indented enough to belong to the parent list item, or a blank line changed the container context.
Are blockquotes only for quotations?
No. They can represent quotations, callouts, warnings, or examples, but your renderer and design system determine how they appear.
Related tutorials
- Review block rules in Markdown Block Parsing and Precedence Rules.
- Compare heading boundaries in Markdown Headings, Paragraphs, Line Breaks, and Thematic Breaks.
- Add nested examples safely with Markdown Code Spans, Fenced Code Blocks, and Raw HTML.
- Test nested structures in CommonMark Test Suite and Dingus.
- Model containers as nodes in Markdown AST with mdast.
Continue with Code Spans, Fenced Code Blocks, and Raw HTML.