Definition list rendering inconsistent when nested inside bullet lists
0 reputation · 23 Nov 2023, 13:49 UTC
0 reputation · 23 Nov 2023, 13:49 UTC
When a definition list appears inside a bullet list, the rendering varies across Markdown engines. The goal is to determine how CommonMark‑supported processors treat such nesting.
The CommonMark spec defines a definition list as a term followed by a colon and indented definitions, but it does not specify whether a definition list can be nested within another definition list or inside a list item. Some processors (e.g., Pandoc with the deflist extension) parse nested lists recursively, while others emit them as plain text.
This ambiguity leads to inconsistent output and potential loss of formatting. The current spec only provides examples, not normative rules, leaving the behavior open to interpretation.
What are the normative rules, if any, for nesting definition lists inside other lists in CommonMark? How should a processor signal that it supports or rejects nested definition lists? What is the recommended approach for authors who need stable rendering across engines?
31775 reputation · 23 Nov 2023, 18:31 UTC
There are no normative rules, because the premise contains a factual error: the CommonMark specification does not define definition lists at all. Through at least version 0.31.x, the spec covers headings, paragraphs, lists, block quotes, code, and so on — but no term/definition syntax. What you're describing as a "CommonMark definition list" is an extension feature, and each processor that offers one (Pandoc, PHP Markdown Extra, kramdown, markdown-it plugins) invented its own rules. The inconsistency you observe isn't an ambiguity in a shared standard; it's the expected result of comparing different, independent extensions.
Confirmed: Definition lists are absent from the CommonMark spec — you can verify this in seconds by scanning the spec's table of contents. GitHub Flavored Markdown, a CommonMark superset, also does not support them, so any document targeting GitHub will render your definition lists as plain paragraphs and stray colons.
Likely, but version-sensitive: Pandoc's definition_lists extension generally permits block content — including nested lists — inside a definition when that content is indented to the definition's column. However, the interaction with a surrounding bullet list depends entirely on indentation, and the same source can parse as a nested definition list in one engine, a code block in a second, and literal text in a third. Treat any specific nesting behavior as a property of one processor at one version, not of "Markdown."
There is no standardized capability mechanism. Support is expressed only through documentation and opt-in flags — Pandoc's +definition_lists, a markdown-it plugin registration, kramdown's built-in syntax. A processor that lacks the extension doesn't "reject" nested definition lists; it simply never recognizes the syntax, and the text falls through to paragraph parsing. The only reliable way to know what a given engine does is to render your exact source snippet in it and inspect the HTML.
If the document must render consistently across engines, don't use definition lists. Use a bullet list with a bolded term, which every CommonMark-compliant processor renders identically:
- **Term one** — its definition here
- **Term two** — another definitionIf you genuinely need semantic <dl> output, pin a single processor (for example, Pandoc with the extension explicitly enabled) in your build pipeline and treat its output as canonical. Verify by rendering one representative nested snippet through every target engine and diffing the HTML before committing to the syntax.
One caveat: if your documents must also preview correctly on GitHub, even the pinned-processor strategy fails there — the fallback bullet form is the only option that survives everywhere.
Use comments to ask for clarification. Post a solution as an answer.
No question comments on this page.