{
  "id": 14598394,
  "title": "My HTML-to-Markdown converter shipped tables my spreadsheet API couldn't parse — the colspan lie",
  "url": "https://urgent.news/2026/10/15/my-html-to-markdown-converter-shipped-tables-my-spreadsheet-api",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-10-15T03:02:53.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/imapphelp/my-html-to-markdown-converter-shipped-tables-my-spreadsheet-api-couldnt-parse-the-colspan-lie-1c5"
  },
  "original_language": "en",
  "account": "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.\n\nUpon 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.\n\nThe 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.\n\nThis 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.",
  "summary": "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…",
  "key_points": [
    "Converter mishandles colspan, causing column shift in downstream XLSX parsing",
    "Markdown spec lacks column-spanning cell representation",
    "Grid mode expands colspan, enabling reliable structured data parsing"
  ],
  "editors_take": "Prioritizing visual aesthetics over structural integrity in Markdown tables creates significant data corruption risks for automated pipelines that require consistent column counts to parse information accurately.",
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}