fix(serializer): derive markdown table header rows from column_header flags

[acharyaanusha]

Fixes #722.

MarkdownTableSerializer hardcoded grid row 0 as the only header row, while TableItem._export_to_dataframe_with_options, the HTML serializer and export_to_otsl all derive the header rows from TableCell.column_header. A table with a stacked header serialized to Markdown with its lower header rows demoted to data rows, and HybridChunker repeated only the first of them atop each chunk of an oversized table.

This takes the header row count from the flags and flattens those rows into the single header row GFM allows, dropping the repeated text a cell spanning several header rows produces (so human / human stays human, not human human).

When no cell in the table carries column_header, the previous behavior is kept. Backends that never set the flag cannot be told apart from genuinely headerless tables, and several *.dt.json fixtures round-trip with zero flags. Making it unconditional instead changed output for those too, so I left it — see the first open question in #722 if you would rather it be strict.

Ground truth

Five ground-truth files are regenerated. Every diff recovers real column names from the body:

• 2206.01062.yaml.md / .paged.md (DocLayNet) — class label | Count | % of Total Train | ... was a body row under a header of % of Total repeats; likewise MRCNN R50 / MRCNN R101, Class-count Split, Testing on PLN
• 2408.09869v3_enriched_p1_mark_meta_{true,false}.gt.md — native backend TTS | native backend Pages/s | native backend Mem
• 0b_out_chunks.json / 0d_out_chunks.json — the same headers as repeated in chunks

Numeric columns shift to right-alignment in a few places, because _column_type no longer sees the former header row when detecting the column type.

Verification

• Full docling-core suite: no new failures, +3 from the tests added here. My environment has pre-existing unrelated failures (missing cv2 stubs, doclang schema resources, and a Pillow that re-encodes the fixture PNGs), so I diffed the failure sets before and after rather than trusting the totals; the sets are identical.
• ruff format, ruff check, and mypy clean on the changed files.
• End-to-end on a live conversion: converted arXiv 2408.09869 with docling 2.120.2 and diffed the full 248-line Markdown export before and after. Exactly one table changes; the two single-header tables in the same document are byte-identical.

Tests

Three cases in test/test_serialization.py: a stacked header flattened, repeated span text deduplicated, and a table with no header flags keeping its first row as the header.

[github-actions]

✅ DCO Check Passed

Thanks @acharyaanusha, 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

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

Files with missing lines	Patch %	Lines
docling_core/transforms/serializer/markdown.py	96.15%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!