Mastering Markdown Lists: CommonMark & GitHub Flavored Markdown (GFM) Indentation Standards
The Technical Foundation of Markdown List Rendering
Markdown has established itself as the standard markup language for modern software documentation, technical specification documents, personal knowledge bases, and developer communication. While single-level bulleted lists (- item) and numbered lists (1. item) appear simple, constructing deeply nested, multi-tiered document outlines introduces significant formatting complexity. Different Markdown parsers—such as CommonMark, GitHub Flavored Markdown (GFM), Python-Markdown, and Pandoc—enforce strict, subtle rules regarding list marker selection, tab-to-space ratios, and sub-block indentation.
When lists are pasted across heterogeneous text editors (like VS Code, Sublime Text, Xcode, Apple Notes, or Microsoft Word), silent indentation errors occur. A single missing space on a sub-item causes the Markdown compiler to interpret a nested child node as a primary top-level item or an isolated paragraph block. Utiliome's Nested List & Indentation Formatter eliminates these parsing anomalies by parsing your input text structure AST (Abstract Syntax Tree) and regenerating standardized, specification-compliant Markdown.
Indentation Rules: 2-Space vs. 4-Space Guidelines
One of the most frequent debates in technical documentation design is whether to indent sub-lists using 2 spaces or 4 spaces per hierarchical tier. The choice depends on the target Markdown parser specification:
The 2-Space Indentation Rule (Standard GFM & Prettier): In modern web documentation ecosystems like GitHub, Docusaurus, Nextra, and Obsidian, 2 spaces per indentation level is the recognized standard. The 2-space convention aligns child content under the text start of the parent item:
- Top-level item 1 - Nested child item 1.1 - Nested child item 1.2 - Deeply nested grandchild item 1.2.1 - Top-level item 2The 4-Space Indentation Rule (Strict CommonMark & Python-Markdown): Strict CommonMark implementations require child blocks, code snippets, and nested lists inside ordered lists to be indented by 4 spaces (or 1 full tab stop) to guarantee proper parent block containment:
1. First ordered step in workflow - Associated sub-bullet A - Associated sub-bullet B 2. Second ordered step in workflowTab vs. Space Traps: Mixing physical tab characters (
\t) with ASCII space characters (\x20) is the leading cause of broken Markdown documentation rendering. Web rendering engines translate tabs inconsistently (often as 4 or 8 display columns), causing nested items to jump visually out of alignment. Utiliome automatically converts all tab characters into uniform space strings according to your explicit configuration preference.
Normalizing Bullet Markers & Ordered Sequence Fixing
Markdown supports three distinct bullet characters for unordered lists: hyphens (-), asterisks (*), and plus signs (+). While all three produce valid unordered lists HTML elements (<ul>), mixing marker types within the same document creates visual clutter and fails automated linter checks (such as markdownlint rule MD004).
Furthermore, ordered list numbering frequently breaks during iterative editing. Authors frequently paste items into the middle of numbered sequences or rely on auto-incrementing 1. syntaxes:
<!-- Unformatted / Broken Input -->
* Feature A
- Feature B
+ Feature C
1. Initial step
1. Second step (copied from draft)
4. Out-of-order step
Utiliome's formatter normalizes all unordered list markers to your selected unified character (e.g., standardizing every item to -) and re-numbers ordered sequences sequentially (1., 2., 3.) or standardizes them to clean single-digit increments (1., 1., 1.) based on your team's code review style guidelines.