fix(md): restore HTML blocks from source when docling-core escapes code by bercedev · Pull Request #4984 · docling-project/docling

bercedev · 2026-10-22T22:13:11Z

Issue resolved by this Pull Request:
Resolves #4982

The Markdown backend hides each HTML block in a code item, serializes the document to HTML, then strips the <pre><code> and markers to get the HTML back. Since docling-core 2.104.0 escapes code text in the HTML serializer (docling-project/docling-core#894), what came back was <table>…, so the block ended up as a text item instead of a table.

Instead of stripping the markers around whatever the serializer produced, each marked code block is now replaced with the HTML block's original source, kept in order when the block is read. That works the same with docling-core 2.103.x and 2.104.0, and doesn't unescape anything twice (an entity inside the original HTML, like &, stays an entity). The block count check is kept.

#4848 rewrites this path and would also cover it; this is the small fix for the regression in the meantime.

Checklist:

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

test_html_block_becomes_a_table_with_its_entities_intact (a table with A & B in a header) fails on main with docling-core 2.104.0 and passes with this. tests/test_backend_markdown.py: with docling-core 2.103.1, 43 passed; with 2.104.0, 42 passed and test_convert_valid fails only on escaped_characters.md, the plain-text & < export change in 2.104.0, which fails on main too and isn't about HTML blocks (mixed.md, nested.md and signature_stamp_01.md from the issue pass again). ruff check/format clean.

github-actions · 2026-10-22T22:13:23Z

✅ DCO Check Passed

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

mergify · 2026-10-22T22:13:45Z

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 · 2026-10-22T22:14:57Z

AI triage (advisory)

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

The Markdown backend now keeps the original source of each HTML block. It puts that source back in place of the marked code block. This stops the escaped HTML from the serializer from turning HTML tables into text items.

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

Possible duplicates

PR	State	Signal	Assessment
#4985	open	changes the same code	duplicate: It fixes the same escaping regression in the same lines of `convert()`. It stores each raw HTML block and puts it back by index. Only one of the two changes can be merged.

2 related pull request(s) in the same code

PR	State	Signal	Assessment
#4848	open	referenced as #4848; changes the same code	related: It removes the serialize-and-restore round trip, so it also fixes this regression. Its main goal is wider: keep the Markdown content around HTML blocks intact. The two PRs change the same lines in `convert()`, so they conflict.
#4771	open	changes the same code	related: The shared lines are one part of a larger ASR feature PR. Those lines fix the same escaping problem, but with `unescape`. This PR restores the original source instead.

_{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): blocker found

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

The Markdown HTML block fix restores original HTML block content correctly. The PR branch includes unrelated OpenDocument backend changes from PR #4956 that you must remove before merge.

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

github-actions · 2026-10-22T22:17:14Z

    return _normalize_odf_text_runs(runs)


+def _odf_list_headings(odf_list: OdfList) -> list[Header]:


blocker: Unrelated OpenDocument changes included in Markdown pull request

The pull request title and description target the Markdown HTML block restoration fix (#4982). The branch also contains changes to docling/backend/opendocument_backend.py and tests/test_backend_opendocument.py from PR #4956.

Merging this pull request will merge OpenDocument list-heading changes under the fix(md) scope.

Rebase the branch onto main and drop the commits that belong to PR #4956.

codecov · 2026-10-23T06:58:42Z

Codecov Report

❌ Patch coverage is 82.14286% with 5 lines in your changes missing coverage. Please review.

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

📢 Thoughts on this report? Let us know!

…ity policy on PyPI docling-core 2.104.0, the first version that allows Pillow 13, escapes the text of code blocks in its HTML serializer (docling-project/docling-core#894). Docling's Markdown backend passes each HTML block through a code block, so an HTML block in a Markdown file, e.g. a table, now comes out as its markup, and Document.from_docling() gives one paragraph of that text where it gave a table header and a paragraph for each row. The changelog lists it under Known issues, with the report to Docling (docling-project/docling#4982), and says that upgrading to a Docling release that reads the HTML blocks as before brings the earlier paragraphs back, without a new release of ContextGem. The fix proposed in docling-project/docling#4984 was checked against that: applied to Docling 2.142.0 with docling-core 2.104.0, it gives the outputs committed before the regression for mixed.md, nested.md and signature_stamp_01.md, and for escaped_characters.md all but the inline code, whose entities docling-core now keeps on purpose. It is not merged, so the changelog does not name a release. [project.urls] has a Security entry for SECURITY.md, which PyPI shows next to the changelog from this release. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Signed-off-by: berce <75228263+bercedev@users.noreply.github.com>

bercedev · 2026-10-23T14:50:18Z

dropped the odf commit, it came along from my #4956 branch by mistake. this PR is only the markdown html block fix now, the odf part stays in #4956.

bercedev · 2026-10-24T11:46:58Z

main fixed this in 53c11a2 (#4771) by unescaping each marked block, so closing this one. that commit didn't add a test though, happy to open a test-only PR with the regression case from here if you want it.

github-actions Bot reviewed Oct 22, 2026

View reviewed changes

github-actions Bot added the ai:review-changes AI first review suggests changes label Oct 22, 2026

github-actions Bot mentioned this pull request Oct 23, 2026

feat(ASR): add transformers and MLX presets for the ASR pipelines #4771

Merged

3 tasks

fix(md): restore HTML blocks from source when docling-core escapes code

ddc7f3b

Signed-off-by: berce <75228263+bercedev@users.noreply.github.com>

bercedev force-pushed the fix/md-html-block-escaped branch from ba7f028 to ddc7f3b Compare October 23, 2026 14:50

julienbrodier mentioned this pull request Oct 24, 2026

Markdown: HTML blocks come out as literal text with docling-core 2.104.0 #4982

Open

bercedev closed this Oct 24, 2026

github-actions Bot mentioned this pull request Oct 25, 2026

fix(md): keep backslash escapes inside the surrounding text #4991

Open

3 tasks done

Navigation Menu

Repository navigation

fix(md): restore HTML blocks from source when docling-core escapes code - #4984

fix(md): restore HTML blocks from source when docling-core escapes code#4984
bercedev wants to merge 1 commit into
docling-project:mainfrom
bercedev:fix/md-html-block-escaped

bercedev commented Oct 22, 2026

Uh oh!

github-actions Bot commented Oct 22, 2026

Uh oh!

mergify Bot commented Oct 22, 2026

🟢 Enforce conventional commit

Uh oh!

github-actions Bot commented Oct 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot left a comment

Uh oh!

github-actions Bot Oct 22, 2026

Uh oh!

codecov Bot commented Oct 23, 2026 •

edited

Loading

Uh oh!

bercedev commented Oct 23, 2026

Uh oh!

bercedev commented Oct 24, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		return _normalize_odf_text_runs(runs)


		def _odf_list_headings(odf_list: OdfList) -> list[Header]:

Conversation

bercedev commented Oct 22, 2026

Uh oh!

github-actions Bot commented Oct 22, 2026

Uh oh!

mergify Bot commented Oct 22, 2026

Merge Protections

🟢 Enforce conventional commit

Uh oh!

github-actions Bot commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

AI triage (advisory)

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

AI first review (advisory): blocker found

Uh oh!

github-actions Bot Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

bercedev commented Oct 23, 2026

Uh oh!

bercedev commented Oct 24, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions Bot commented Oct 22, 2026 •

edited

Loading

codecov Bot commented Oct 23, 2026 •

edited

Loading