My HTML-to-Markdown converter shipped tables my spreadsheet API couldn't parse — the colspan lie
Built the HTML-to-Markdown endpoint so agent pipelines could turn messy web pages into clean Markdown. Tables looked perfect in my tests: pipe tables, aligned columns, the works. Then I pointed my XLSX converter at the output and watched it silently produce garbage — every row after a colspan was shifted one column left, and no error anywhere. Turned out the Markdown table spec has no way to…
I developed an HTML-to-Markdown converter to enable agent pipelines to transform complicated web pages into clean Markdown. Initially, tables appeared flawless during testing, displaying pipe tables and aligned columns. However, I encountered an issue when feeding the converted output to my XLSX converter; it produced garbage data, with every row after a colspan shifted one column to the left, without triggering any error messages.
Upon investigation, I discovered that the Markdown table specification lacked a way to represent a cell spanning two columns. My converter inadvertently emitted cell text in one cell, then the next cell's text in the subsequent cell, leading downstream components to shift their columns. This discrepancy meant that while a human reading the rendered table could comprehend the alignment, a parser consuming the pipe syntax would interpret the table as having the incorrect number of columns per row.
The solution didn't lie within the Markdown format itself. Instead, I introduced a table_mode option to the HTML converter, offering two modes: markdown (the default, human-readable) and grid (which expands colspan and rowspan into repeated cells, ensuring every row maintains an identical column count). Although the grid mode produces output that appears duplicated and less aesthetically pleasing, it is the sole version capable of being reliably parsed back into structured data by agents.
This experience reaffirmed a critical lesson for me: a format that looks correct to a human eye does not necessarily align with a format that a machine can accurately reverse-engineer. Markdown tables, while visually appealing, operate as display formats masquerading as data formats. When constructing pipelines that convert HTML → Markdown → table data, it is essential to rigorously test the round trip rather than solely focusing on rendering.
To accommodate both modes, I packaged the converter at https://x402.freeq.one/tools/html_to_markdown.html, where specifying table_mode=grid directs the output to feed a parser rather than a prompt.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
