fix(serializer): collapse multi-row column headers into one markdown header

[scottf007]

Summary

MarkdownTableSerializer hardcoded headers=rows[0] and rows[1:]. When TableFormer correctly marks multiple leading rows as column_header=True (e.g. "Cash per Security" + "($)" on successive grid rows), only the first rendered as the markdown header and the continuation leaked into the body as a spurious data row.

Mirrors _export_to_dataframe_with_options (document.py:2219-2245): count leading grid rows containing any column_header cell, concatenate per column for the header, use the rest as body. Spanning siblings render empty so a colspan=N header isn't concatenated N times.

Falls back to "first row is header" when no column_header cells are marked — preserves prior behaviour for that path.

Empirical result

10-PDF corpus, byte-comparison of rendered markdown:

• IOZ_2025_04_17.pdf: 2-row header collapses into 1. Body unchanged.
• 9 other fixtures: byte-identical.

Related: docling-project/docling#2985.

[github-actions]

✅ DCO Check Passed

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

[cau-git]

@scottf007 Thanks for this proposal, having headers correctly separated from table bodies would clearly be an improvement. However, this behaviour is exactly intended in the default serializer: "Spanning siblings render empty so a colspan=N header isn't concatenated N times." so we would like to keep it. Do you want to update the PR with this?

[scottf007]

Thanks @cau-git — appreciate you taking a look.

Quick clarification so I update the right thing: the PR already preserves the "spanning siblings render empty so a colspan=N header isn't concatenated N times" behaviour — that line in the description is describing what the patch keeps, not something it changes. The only behavioural change is that multiple leading rows marked column_header=True now collapse into a single markdown header row instead of the continuation rows leaking into the table body (e.g. a column title that wraps onto two visual lines like "Cash per Security" + "($)"). On the 10-PDF corpus only that one fixture changed; the other 9 were byte-identical.

So I'm not sure which part you'd like me to keep vs. change — happy to adjust, just want to make sure I understand. Is the concern that the multi-row collapse itself shouldn't be the default, or something about how the concatenation is done?

Separately: I've fixed the DCO check (the previous remediation commit referenced the wrong SHA).

Some broader feedback while I'm here, in case it's useful: the cases that bit me most were multi-column tables with sparse/empty columns where cells lose their x-position alignment, content occasionally getting dropped from the parse entirely, and flaky header detection. Alignment guards (inter-line/word/column distance heuristics) as a sanity check over the neural output might help — I know that's messy across hundreds of table shapes. Either way I think docling's a great project and want to help where I can.