If an HTML table with merged cells comes out of an HTML-to-Markdown conversion misaligned or incomplete, the target format may be the reason. Ordinary GitHub Flavored Markdown (GFM) pipe tables cannot encode colspan or rowspan, so they cannot preserve the same merged-cell structure. Keep the table in HTML where supported, or reshape its content for Markdown.
Why merged cells break in GFM pipe tables
An HTML table can use colspan to make one cell cover multiple columns and rowspan to make it cover multiple rows. GFM pipe tables have a fixed header and delimiter structure instead; they do not provide attributes for spanning cells. MDN’s Markdown guidance explicitly lists colspan and rowspan among the table attributes GFM does not support: MDN, “How to write in Markdown”.
As an Amazon Associate I earn from qualifying purchases.
That means a converter can read the HTML source yet still lack a way to represent its merged-cell layout in the selected Markdown flavor. The result may have rows that no longer align with the logical columns. GFM specifies how to handle rows with too few or too many cells: missing cells are inserted and excess cells are ignored. Depending on how a converter emits a row, content can therefore appear shifted or be lost. See the GFM specification.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteChoose a workaround based on the destination
| Approach | When it fits | Trade-off |
|---|---|---|
| Keep the table as HTML | The destination allows and preserves raw HTML tables and span attributes. | Retains merged-cell structure where supported; renderer compatibility is required. |
| Expand the table into a rectangular grid | The destination requires a GFM pipe table and repeated values remain understandable. | Preserves information by repeating labels or values, but does not create native merged cells. |
| Use prose or lists | Repeated entries would be confusing, or the table is irregular. | Changes the presentation, but may make relationships easier to follow. |
Keep the table as HTML
If raw HTML is accepted by the destination, retain the original table markup, including its span attributes. MDN recommends HTML when a GFM table needs unsupported features. Check the destination renderer rather than assuming that it will allow or preserve the markup.
#1 Best Overall
Expand spans into a rectangular grid
If pipe-table output is mandatory, represent each logical column explicitly. Repeat the spanning label or value in every cell it covers, then compare each row with the original HTML table. This is a workaround that makes the relationships explicit; it is not merged-cell support in Markdown.
Switch to prose or lists for irregular relationships
For a table where repeating labels would obscure which values belong together, describe the groups in prose or use nested lists. A fixed pipe grid is not always the clearest way to communicate data that was organized with irregular spans.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What Pandoc conversion does—and does not—guarantee
Pandoc documents this general HTML-to-Markdown command:
pandoc -f html -t markdown hello.html
It converts from an HTML input format to a Markdown output format, but that alone does not guarantee that merged-cell semantics survive. The output has to fit the chosen Markdown flavor, and GFM cannot encode these spans. Review the generated table against the original and check how the destination renders it. See the Pandoc User’s Guide and the GFM specification.
Quick Recap
Check the conversion before publishing
- Compare every output row with the source table, especially rows affected by a span.
- Look for missing cells, shifted values, or content that appears under the wrong heading.
- Confirm that the selected destination accepts raw HTML if you keep the original table markup.
- If converting to a pipe table, ensure each row matches the logical grid and that any repeated labels remain clear.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
