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

Description and use

The HTML‑to‑Markdown converter misaligned tables using colspan/rowspan, causing downstream errors. Solutions: unroll colspan, emit original HTML for rowspan, add mode flag, and regression tests with pipe escaping.

Problem

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

Outcome

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

Workflow

• 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.

Evidence

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.

Source

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.

Source

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.

Source