[cau-git]

Summary

The Markdown backend converts documents that contain raw HTML blocks by round-tripping through HTML. It puts each raw block into a CodeItem between markers, serializes the document to HTML, and swaps each marked <pre><code> block back for the raw HTML.

Since docling-core 2.104.0 (docling-core#894) the HTML serializer escapes code text. #4771 adapted to this by unescaping each marked block once. That assumes the serializer escaped the block exactly once, which only holds for 2.104.0 and later:

docling-core	main	this PR
2.104.0	correct	correct
2.103.1 (allowed by the current floor)	entities in raw HTML decoded twice: & becomes &	correct

Change

• fix(md): the backend stores the raw blocks in a list and puts only an index between the markers. convert() replaces each marked block with the stored HTML, so the result no longer depends on how the serializer treats code text. That includes any future change to its escaping.
• build: raises the floor to docling-core>=2.104.0. The Markdown groundtruth (escaped_characters.md) already expects literal & inside code spans and code blocks. Only 2.104.0 produces that; older cores decode code text a second time in the round trip. The lock already resolves 2.104.0, so only the specifiers change.

Testing

• New test_html_block_entities_are_decoded_exactly_once: the entities in a raw HTML block reach the output decoded exactly once.
• On docling-core 2.104.0, the Markdown and HTML backend tests pass: 181 passed, 1 skipped.
• On docling-core 2.103.1, the new test passes. The only failure is the escaped_characters golden, which needs 2.104.0; that is why the floor is raised.

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary.

🤖 Generated with Claude Code

[github-actions]

✅ DCO Check Passed

Thanks @cau-git, 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 a561ec188c. The analysis read the diff only. It did not run code from this pull request.

This PR stores raw HTML blocks in a list and inserts numeric index placeholders into code items during Markdown conversion. It restores the stored HTML blocks by index to prevent incorrect entity decoding.

Topic labels added: bug, markdown.

CI safety: needs maintainer care before you approve CI.

• pyproject.toml: changes build, dependency, or tool configuration
• uv.lock: changes locked dependencies

Possible duplicates

PR	State	Signal	Assessment
#4985	open	changes the same code	duplicate: PR #4985 implements the same indexed list mechanism to restore raw HTML blocks in md_backend.py.

1 related pull request(s) in the same code

PR	State	Signal	Assessment
#4771	merged	referenced as #4771	related: PR #4771 changed the same HTML block restoration code in md_backend.py with an unescape approach.

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

[codecov]

Codecov Report

❌ Patch coverage is 85.71429% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/backend/md_backend.py	85.71%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!