[sarankumar1325]

An image caption (taken from a <figcaption>, a linked image, or the alt text) was added with doc.add_text() and no parent, so it went into body. In a page with sections, the caption ended up outside its picture's section: between section "One" and section "Two" in the issue's example.

_emit_image now adds the picture first, then adds the caption as a child of the picture and links it in captions. The PDF reading-order model does the same. As a result, the caption stays with its picture when the picture is a child of a section and also when group_cell_elements moves the picture into a rich table cell group.

Issue resolved by this Pull Request:
Resolves #5036

Checklist:

• Documentation has been updated, if necessary. (n/a)
• Examples have been added, if necessary. (n/a)
• Tests have been added, if necessary.

Review evidence:

• Before: with the HTML from the issue, body.children was the title "One", then the caption "Caption text", then the title "Two". Section "One" held only the picture and "Para one.".
• After: body.children is the two titles. Section "One" holds the picture and "Para one.". The caption is the picture's only child and is still in picture.captions.
• New test_image_caption_stays_in_the_section_of_its_image is parametrized for a <figcaption> and an alt-text caption. Both cases fail on main and pass with this change.
• Reference data was regenerated with DOCLING_GEN_TEST_DATA=1 for example_01, example_01_images, html_rich_table_cells, hyperlink_02, hyperlink_05 and wiki_duck. In the JSON, the only change is the parent of each image caption, which moves from #/body to its picture. The .itxt trees list the caption under the picture: once as the child and once from captions. No Markdown reference file changed.
• uv run pytest tests/test_backend_html.py tests/test_backend_markdown.py tests/test_backend_mhtml*.py: 194 passed, 1 skipped.
• ruff format --check and ruff check are clean. ty check docling/backend/html_backend.py reports the same 27 diagnostics as on main.
• I did not run the full test suite.

This fix was prepared with AI assistance; I reviewed the change and ran the checks above.

[github-actions]

✅ DCO Check Passed

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

[mergify]

Merge Protections

🔴 1 of 2 protections blocking · waiting on 👀 reviews

	Protection	Waiting on
🔴	Require two reviewer for test updates	👀 reviews
🟢	Enforce conventional commit	—

🔴 Require two reviewer for test updates

Waiting for

• #approved-reviews-by >= 2

This rule is failing.

When test data is updated, we require two reviewers

• #approved-reviews-by >= 2

---

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 166d32bb1b. The analysis read the diff only. It did not run code from this pull request.

The HTML backend now adds an image caption as a child of its picture and links it in captions. Before, the caption went into body and could leave the section of its picture.

Topic labels added: bug, html.

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

1 related pull request(s) in the same code

PR	State	Signal	Assessment
#3891	open	changes the same code	related: The PR title says it adds an InlineGroup whitespace rule to the backends. This PR moves image captions under their picture. Both touch html_backend.py and test_backend_html.py, but they do different things.

Reference data changes

Change	Files
structure	6
text	4

• structure tests/data/html/groundtruth/example_01.html.json: reading order changed
• structure tests/data/html/groundtruth/example_01_images.html.json: reading order changed
• structure tests/data/html/groundtruth/html_rich_table_cells.html.json: reading order changed
• structure tests/data/html/groundtruth/hyperlink_02.html.json: reading order changed
• structure tests/data/html/groundtruth/hyperlink_05.html.json: reading order changed
• structure tests/data/html/groundtruth/wiki_duck.html.json: reading order changed
• text tests/data/html/groundtruth/example_01.html.itxt: +10 / -10 lines
• text tests/data/html/groundtruth/html_rich_table_cells.html.itxt: +3 / -3 lines
• text tests/data/html/groundtruth/hyperlink_05.html.itxt: +6 / -6 lines
• text tests/data/html/groundtruth/wiki_duck.html.itxt: +1278 / -1278 lines

Assessment: expected. The code change makes the caption a child of its picture instead of body. This matches the reading-order changes in the .json files and the moved caption lines in the .itxt files. The large wiki_duck.html.itxt change is a bulk line change in a text tree, and I could not inspect its content.

_{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 166d32bb1b. It read the code and did not run it.

I checked the HTML image caption hierarchy change and its test coverage. Image captions now attach to their picture item as children and keep the correct section structure without breaking document exports.

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