Nested Markdown list renders as code block in one renderer, nested list in another

Question

I maintain documentation that must render correctly in more than one Markdown toolchain, and nested lists are the sticking point. The same source — a - a item with a - b child indented two spaces — can produce a nested ul, a flattened continuation paragraph, or an indented pre/code block depending on the renderer, with no error reported in any of them.

My understanding is that CommonMark measures a list item's content column relative to its marker (so two-space nesting works), while renderers following older Markdown.pl conventions, such as Python-Markdown's default behavior, historically expect four-space indentation. GFM builds on CommonMark, so GitHub-style renderers accept the two-space form. I also assume tabs are unreliable here because tab-stop handling differs across parsers.

What I cannot resolve is a portable authoring rule I can enforce across contributors without knowing every downstream renderer, and how much I can trust a parser that merely claims "CommonMark conformance" when spec revisions (the 0.27–0.31 line) have tightened list rules over time.

Is four-space indentation of nested items actually sufficient and safe across CommonMark, GFM, and Markdown.pl-style renderers, or are there documented cases where it still diverges?

When a pinned parser and a current parser both claim CommonMark conformance, what is the practical way to confirm which list-indentation behavior my toolchain implements — is comparing output in a reference dingus or Babelmark considered authoritative?

Tasadduq Burney · Answer

AnswerFour‑space indentation of a nested list item is sufficient and safe across CommonMark (spec 0.27+), GitHub Flavored Markdown (GFM), and legacy Markdown.pl‑style renderers. It will produce a nested ul in all of them and will not be mistaken for a code block or flattened paragraph.ExplanationCommonMark defines the content column of a list item as the column after the marker plus any optional spaces. A nested list is recognised when its marker starts at least two spaces after the parent marker. Therefore both two‑space and four‑space indentation satisfy the rule. Older Markdown.pl implementations, however, historically required four spaces (or a tab) to start a new list level; with fewer than four spaces the inner marker was treated as plain text, often resulting in a flattened paragraph or, if the line began with a backtick, an unintended code block. GFM follows CommonMark, so it accepts both two‑space and four‑space forms.Confirmed factsCommonMark 0.27‑spec and later: two‑space minimum for nesting; four‑space works.GFM: identical to CommonMark for list indentation.Markdown.pl (and many early derivatives): four‑space requirement; less than four spaces yields non‑list output.Tabs are unsafe because tab‑stop width varies and parsers differ on whether a tab counts as the required indentation.Portable authoring ruleUse exactly four spaces (no tabs) before the marker of any nested list item. This satisfies the strictest legacy rule while remaining well within the CommonMark/GFM minimum.Verification stepsCreate a test Markdown snippet:- a - b - c - d Render the snippet with each target toolchain:CommonMark reference implementation (e.g., cmark)GFM renderer (e.g., GitHub’s API or github-markdown)A Markdown.pl‑based renderer such as Python‑Markdown default (markdown.markdown)Inspect the output: the lines - b and - c should appear as nested

 block.Optionally, compare the rendered HTML to the reference dingus or Babelmark tables for the same input; agreement across those references confirms the parser’s list‑indentation behavior.DiagramCommonMarkGFMMarkdown.pl

Nested Markdown list renders as code block in one renderer, nested list in another

1 answer

Answer

Explanation

Confirmed facts

Portable authoring rule

Verification steps

Diagram

Your perspective belongs here.

0 question comments