Colspan tables shredded my HTML-to-Markdown output — Markdown can't express merged cells

说明与用途

HTML 转 Markdown 转换器无法正确处理合并单元格的表格，导致列错位并影响下游 RAG 流程。解决方案包括展开 colspan、保留原始 HTML 以处理 rowspan、添加模式选择标志，并通过回归测试检测并转义管道字符。

问题

HTML-to-Markdown conversion produced misaligned tables when source tables used colspan and rowspan, leading to incorrect data in downstream RAG pipelines.

结果

The converter now correctly handles tables with merged cells by either unrolling colspans or preserving original HTML, preventing misalignment and downstream errors.

工作流

• 1. Detect tables with colspan or rowspan.
• 2. If only colspan, duplicate merged value into each covered cell (unroll).
• 3. If rowspan present, emit original <table> HTML verbatim.
• 4. Provide a flag to force a chosen mode.
• 5. Run regression test: round-trip Markdown to HTML and compare cell counts; escape literal pipe characters in cells.

证据

My converter processed each row independently — row <td> count became pipe count. Rows under a colspan came out shorter, and whichever Markdown parser consumed the file aligned what came next with whatever column was open.

来源

Three approaches I tried: 1) Unroll colspans by duplicating the merged value into every covered cell. 2) Rowspan is nastier — cell offsets shift for all following rows, so duplicating values downward made a 30-row spec sheet explode into mush. 3) Knob, not heuristic-by-default: a flag lets callers force one table mode or the other.

来源

The regression test caught a second bug immediately: round-trip the output through a Markdown-to-HTML renderer and compare cell counts per row against the source table. Two tables failed — cells containing literal pipe characters were splitting into two cells, shifting everything after them. Escaping | inside converted cells fixed it.

来源