HTML block (type 7) glued to a list item is treated as lazy continuation; cmark and commonmark.js close the list

[amirbiron]

Minimal input

## Opts

- a
<br>
## Next

What markdown-it-py does (3.0.0 and 4.2.0; the JS original 14.3.2 behaves identically)

<br> is taken as a lazy continuation of the list item's paragraph, so ## Next becomes a second heading:

<h2>Opts</h2>
<ul>
<li>a
<br></li>
</ul>
<h2>Next</h2>

What cmark-gfm (via cmarkgfm 2025.10.22) and commonmark.py 0.9.2 (port of commonmark.js) do

The list is closed, <br> opens a type-7 HTML block, and the block swallows ## Next until a blank line:

<h2>Opts</h2>
<ul>
<li>a</li>
</ul>
<br>
## Next

The same holds for <span>, </pre> and <img src="x">. With a blank line between - a and the tag, all three implementations agree.

Why it matters

Two reference-lineage implementations (cmark, commonmark.js) agree against markdown-it. Anything that maps headings to line numbers against GitHub's rendering sees a phantom heading here.

Mechanism: rules_block/html_block.py marks the type-7 sequence as "cannot terminate a paragraph", and list.py's terminator check therefore lets the line continue the item's paragraph lazily. cmark performs the "can this line start a block?" check against the outer container once the list item failed to match, so the type-7 restriction (which is about interrupting a paragraph) does not apply there.

Flipping the terminate flag for type 7 is not a fix — measured: it makes <br> interrupt a paragraph with no list at all, where all implementations currently agree.

Found while building a differential test suite for a Markdown section parser (amirbiron/CodeBot#3418); the shape is pinned there as a known divergence.

[saitakarcesme]

I reproduced this against current master and compared the results with both commonmark.py 0.9.2 and cmarkgfm 2025.10.22. Two extra boundary cases may be useful when implementing the fix:

-    a
    <br>
## Next

Here the four-space <br> must remain in the list paragraph. Both reference parsers agree with the current output. Simply allowing type-7 termination whenever sCount[startLine] < blkIndent fixes the reported example but changes this case into a code block outside the list.

Checking the parent list's indentation also needs care with multiple ancestors:

100. a
     - b
    <br>
## Next

The tag again remains in the innermost paragraph in both references. A guard based only on sCount - listIndent < 4 still terminates it incorrectly: the line has also left the outer item, so the applicable indentation is that of the surviving container, not the immediate parent.

I tested that tentative guard locally: the full existing suite plus 22 new targeted cases passed (1,054 tests), but an additional 804-case comparison over list marker widths, nested lists and indentation found eight regressions. This is why I have not submitted that implementation as a fix. Regression coverage should include these two cases as well as the original example, correctly indented tags, ordinary paragraphs and HTML-disabled mode.

There is also the analogous existing divergence for > a\n<br>\n## Next\n: both reference parsers close the quote before the HTML block. The blockquote rule marks unchecked continuations with negative indentation, so a list-only guard will not cover that path.

AI disclosure: this investigation and local test execution were performed by OpenAI Codex on behalf of @saitakarcesme; no independent human review is claimed.

[amirbiron]

@saitakarcesme

Thanks for the boundary cases — I measured all three against markdown-it-py 3.0.0, cmark-gfm (cmarkgfm 2025.10.22) and commonmark.py 0.9.2 (port of commonmark.js).

A and B (tag indented four spaces inside the item, with one or two ancestors) — full agreement. All three implementations keep the tag inside the item's paragraph, and ## Next is a heading:

-    a
    <br>
## Next

100. a
     - b
    <br>
## Next

So these are exactly the shapes a naive fix would break, and I have pinned them on my side as agreeing shapes so a future change that flips them gets caught (amirbiron/CodeBot#3455).

C (blockquote) — a real additional divergence, same mechanism. With the tag glued to the blockquote line:

> a
<br>
## Next

markdown-it-py takes <br> as a lazy continuation of the blockquote's paragraph and ## Next becomes a heading. cmark-gfm and commonmark.py close the blockquote, <br> opens a type-7 HTML block, and it swallows ## Next — no heading at all. With a blank line between > a and <br>, all three agree.

I confirmed the family behaves identically for -, 1. and >: glued means divergence, blank-line-separated means agreement. So the class is "type-7 tag glued to a container line", not just list items. On my side the pinned divergence now covers the blockquote case too, and the issue title could be widened the same way if you prefer.

Why a guard inside html_block.py cannot be enough — and why the eight regressions are expected. The two guards you tried (sCount < blkIndent, then sCount - listIndent < 4) fail for the reason you already named: the indentation that decides the line's fate is that of the surviving container, not the immediate parent. That information is not available where the terminator runs. StateBlock carries a single blkIndent and a single listIndent ("indent of the current list block"), not the chain of enclosing containers, and the terminator rules are invoked from inside the innermost open block (paragraph, list, blockquote) with only that block's blkIndent in scope. cmark gets the same answer from the other direction: it re-matches the open containers top-down first, so when the list item (or blockquote) fails to match, the "can this line start a block?" check runs against the container that did match, and type 7's "cannot interrupt a paragraph" restriction simply does not apply there. The blockquote path is the same gap in a different coat: blockquote.py runs the terminators itself, gets False for type 7, and then marks the line with sCount = -1, which paragraph.py skips as already checked.

So any fix that only tweaks the type-7 terminator answer is choosing which shapes to break; the missing piece is knowing, at that point, which container the line actually falls back into. I am not proposing a specific design for that, but it does suggest the fix belongs in the block state rather than in html_block.py.

Happy to test any patch against these six shapes (three containers × glued/separated) plus A and B.

[saitakarcesme]

Thanks for independently checking these cases and pinning the agreeing shapes. The surviving-container distinction also explains why the blockquote case cannot be addressed by the list-only guard. I have not submitted the experimental patch because of the eight regressions described above.

For a future fix, the acceptance set should include your six glued/separated container cases plus A and B, the wider ancestor/indentation matrix, and HTML-disabled mode. Before changing StateBlock, maintainer guidance on preserving parity with upstream markdown-it would help determine where this should be fixed. There is no safe implementation ready from this investigation yet.

AI disclosure: this follow-up was prepared by OpenAI Codex on behalf of @saitakarcesme.