[LubabaKhalid]

A Markdown heading or list item does not create its item right away. _iterate_elements() pushes a payload on creation_stack, and the first text run or code span of its content creates the item with that text. Two kinds of content emit neither:

• an image without alt text, for example 1. ![](a.png) or # ![](logo.png);
• inline HTML only, for example # <img src="logo.png" width="80">.

The payload then stays on the stack, and the next text run of the document, in a later block, creates the item with its own text:

• In a list, the next item is created twice: once for the pending item, and once again nested under it.
• A paragraph after the list becomes a list item.
• A paragraph after the heading becomes the heading, and the heading itself is lost.

This change:

• creates the pending item with empty text when an image without alt text is the first content of the list item or heading, like the existing flush for a code span. The picture then goes under its list item, as in the HTML backend.
• creates a payload of a list item or heading that is still pending after one of its children, with empty text. This covers inline HTML. It happens before a nested list is walked, so the nested list goes under the right item.

An image with alt text keeps its current output, because its alt text is a text run.

Checklist:

• Documentation has been updated, if necessary. (Not needed.)
• Examples have been added, if necessary. (Not needed.)
• Tests have been added, if necessary.

Review evidence:

export_to_markdown() before and after:

1. A list item with only an image

1. ![](a.png)
2. Second step
3. Third step

main:

<!-- image -->
1. Second step
    1. Second step
2. Third step

This PR (the same as the HTML backend gives for <ol><li><img src="a.png"></li>...):

1. 
<!-- image -->
2. Second step
3. Third step

2. A nested list under a list item with only an image

- ![](a.png)
  - nested
- next

main: <!-- image -->, - nested, - nested, - next (the nested item is created twice).
This PR: - , <!-- image -->, - nested, - next.

3. A heading with only an image or only inline HTML

Input	main	This PR
#  + Intro paragraph.	<!-- image -->, # Intro paragraph.	# , <!-- image -->, Intro paragraph.
# <img src="logo.png" width="80"> + Intro paragraph.	# Intro paragraph.	# , Intro paragraph.
Setext  / === + Intro paragraph.	<!-- image -->, # Intro paragraph.	# , <!-- image -->, Intro paragraph.

Reference data: no change.

Tests: three new tests in tests/test_backend_markdown.py, with five cases: the list item with only an image (markers, texts, picture under the item), the nested list, and the three heading inputs. All five fail on main.

Checks:

• uv run pytest tests/test_backend_markdown.py tests/test_backend_markdown_images.py tests/test_backend_html.py tests/test_backend_epub.py tests/test_backend_text_encoding.py: 228 passed, 1 skipped
• uv run prek run --files <changed files>: all hooks passed

[github-actions]

✅ DCO Check Passed

Thanks @LubabaKhalid, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[github-actions]

AI triage (advisory)

Checked commit 8544d9431b. The analysis read the diff only. It did not run code from this pull request.

The PR fixes the Markdown backend. A heading or list item with no text run (an image without alt text, or only inline HTML) now becomes an item with empty text. It no longer takes the text of a later block.

Topic labels added: bug, markdown.

CI safety: no concern found. A maintainer must still approve CI.

1 related pull request(s) in the same code

PR	State	Signal	Assessment
#4848	open	changes the same code	related: Both PRs change md_backend.py and tests/test_backend_markdown.py. #4848 changes how HTML blocks are converted, and this PR flushes pending list item and heading payloads. The two fixes are different and can both be merged.

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

[github-actions]

AI first review (advisory): no blocker found

This review covers the full diff at 8544d9431b. It read the code and did not run it.

I found no defect that blocks the merge. I traced the new flush paths in docling/backend/md_backend.py for list items and headings that hold only an image without alt text, or only inline HTML. They flush the pending payload with empty text before a later block can take it. The nested-list case also works: the flush runs after the first child, so a nested list attaches to the right item.

_{A maintainer makes the merge decision. This review never approves the pull request.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[LubabaKhalid]

@dolfim-ibm @PeterStaar-IBM could you please review this PR when you have time? Thank you!

[PeterStaar-IBM]

lgtm!