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 express "this cell spans two columns." My converter emitted the cell text in one cell, the next cell's text in the next, and everything downstream shifted. A human reading the rendered table sees alignment; a parser reading the pipe syntax sees a table with the wrong number of columns per row.
The fix wasn't in the Markdown. I added a table_mode option to the HTML converter: markdown (default, human-readable) and grid (colspan/rowspan expanded into repeated cells, so every row has identical column count). The grid mode makes output uglier — you see duplicated cell text — but it's the only version an agent can reliably parse back into structured data.
Lesson I keep relearning: a format that looks right to a human is not the same as a format a machine can invert. Markdown tables are a display format pretending to be a data format. If your pipeline round-trips HTML → Markdown → table data, test the round trip, not the rendering.
Packaged both modes in the same endpoint: https://x402.freeq.one/tools/html_to_markdown.html — pass table_mode=grid when the output feeds a parser instead of a prompt.
Top comments (0)