fix(asciidoc): block titles, picture parenting, skipped headings, and list dedent

[ceberam]

Fix several structural bugs in the AsciiDoc backend

This PR fixes four independent structural bugs in AsciiDocBackend discovered when reviewing PR #4118 , adds a new test document that exercises all caption variants, and tightens an existing test.

Block titles attached to the wrong element

In AsciiDoc, a line starting with . immediately followed by text (e.g. .Procedure) is a block title — it captions the immediately following element, not the preceding one.
The backend was flushing pending block-title text as a standalone CAPTION item at the moment it encountered the next block, so the caption ended up before or after the wrong element in the DoclingDocument body.

The new contract, documented in _parse's docstring:

• FloatingItem targets (picture, table, code block): the block title is created as a CAPTION-labelled TextItem and attached via the caption= parameter, so it participates in the standard structural caption relationship.
• All other targets (lists, paragraphs, …): the block title is emitted as a bold PARAGRAPH TextItem inserted immediately before the element it precedes. GroupItem has no caption slot, so this is the closest correct representation while preserving reading order.

Pictures always parented to the document body root

doc.add_picture was called with parent=None for all non-list contexts, unconditionally placing every picture at the document body root regardless of which section it appeared in. Pictures are now parented with self._get_current_parent(parents), matching the behaviour of every other element type.

Section headings with skipped levels landing at the body root

When heading levels are skipped in the source (e.g. == followed directly by ==== with no === in between), parents[level - 1] is None and the heading was silently placed at the body root. The backend now walks down from level - 1 to find the nearest populated ancestor, so skipped-level headings nest under the closest available parent instead of floating to the top.

List items orphaned when dedenting past the base indent

When a list started with an indented item and a later item dedented all the way back to indent 0, the dedent loop cleared the only list group from parents and left no valid parent for the dedented item. add_list_item then received parent=None, causing docling-core to emit DeprecationWarning: ListItem parent must be a list group, creating one on the fly and create a structurally orphaned implicit group.

The loop now stops before clearing the last remaining group: if indents[level - 1] is None there is no outer group to fall back to, so the current group is kept as the list root and the dedented item is added to it.

New test document: asciidoc_05.asciidoc

A new example file and its groundtruth markdown have been added to cover all four block-title targets in one document:

• .Figure 1: … before an image:: → caption attached to PictureItem
• .Important Prerequisites / .Steps to complete setup before lists → bold paragraphs before each list
• .Example configuration payload before a .... literal block → caption attached to CodeItem
• .Supported output formats before a |=== table → caption attached to TableItem

Test improvements

The test_local_images_are_embedded_and_missing_images_do_not_break_export test now wraps the conversion in pytest.warns(UserWarning, match="Could not process an image").
This both asserts that the warning is raised when images are missing (the warning becoming a test contract) and prevents it from leaking into the test-run output.

[github-actions]

✅ DCO Check Passed

Thanks @ceberam, 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)(?:\(.+\))?(!)?:

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[PeterStaar-IBM]

lgtm!