GuideBy MarkovoPublished October 20, 2026

HTML tables to Markdown without shifted cells

Convert HTML tables to Markdown as pipe tables when their cells already map to flat fields. Resolve merged cells first, or keep HTML when their structure must survive. The decision turns on four cases: a regular grid with headers, a grid without headers, merged cells, and rich content inside cells. Our local conversions exposed failures that still produced a table: an item moved under the category heading, and an inline code expression caused the final link to disappear.

Choose the representation before converting HTML tables to Markdown

Use a pipe table for flat records, and retain HTML when flattening would change the relationships or content you need.

Apply the structural cases before choosing the header policy when several cases overlap. Links and inline code can fit a pipe table, but a pipe inside the code still needs escaping. A list inside a cell requires a different representation from a short inline label. GFM tables accept inline content, not block elements. ¹

HTML spans describe positions that a cell occupies, not extra copies of a child element. A category cell can occupy the beginning of a later row even though that row has no category element of its own. Reading each row's child cells from left to right loses that occupied position unless the converter tracks it. The HTML table model defines these occupied slots across rows and columns. ²

Use markdownify for flat cells with an explicit header policy

markdownify is useful for flat tables, but its column-span handling does not reconstruct positions occupied by earlier rows.

markdownify can convert a saved fragment with an explicit parser and header policy. This example leaves an empty header when the input has no heading cells. ³

from pathlib import Path
        from markdownify import markdownify
        
        source = Path("input.html").read_text(encoding="utf-8")
        result = markdownify(source, bs4_options="html.parser",
                             table_infer_header=False)
        Path("output.md").write_text(result, encoding="utf-8")
        

Our ordinary grid kept its headings and records. The headerless input also kept both records in the body, underneath an empty header. An empty header satisfies the pipe-table format, but it does not supply missing field names. If the source provides no names, preserve that uncertainty or add names from the surrounding explanation. ⁸

The source placed East beside Apples and Pears with a spanning cell. Its Markdown output omitted the occupied category position from the Pears row.

Output from our merged-category sample, unedited:

| Group | Item | Qty |
        | --- | --- | --- |
        | East | Apples | 12 |
        | Pears | 9 |
        

Both local table readers accepted this output. Pears appeared under Group, while its quantity appeared under Item. The readers added the missing empty cell at the end. ⁸

markdownify's cell handlers add separators for a column span, while its row handler emits the cells it receives without maintaining a map of positions occupied from earlier rows. A spanning cell on the right can leave only a trailing gap; the same shape on the left shifts the fields that follow. The reported rightmost-span example in the project's issue tracker also produced a short row in our run. ⁴⁶

Use Pandoc when the table's HTML structure must survive

Pandoc's GFM writer retained HTML for the merged and block-content samples, preserving structure that a flat pipe table could not express.

Pandoc can write ordinary grids as pipe tables while allowing more complex tables to remain HTML:

pandoc -f html -t gfm --wrap=none input.html -o output.md
        

Our ordinary and headerless grids became pipe tables. The grouped heading and spanning category remained HTML with their span attributes. The cell containing an explicit break kept that break. The cell containing a list kept its list elements instead of turning the bullets into text. ⁸

Output from our list-inside-a-cell sample, unedited:

<td>Apples</td>
        <td><ul>
        <li>Wash</li>
        <li>Slice</li>
        </ul></td>
        

This output is HTML inside a Markdown document. The destination must accept raw HTML for the retained structure to be useful. Disabling HTML forces a representation choice: move the list out of the table, flatten its text, or use a format that carries the structure. Pipe cells cannot hold ordinary block lists or paragraphs. ⁵

We reran the original merged-table input and forced-pipe command from a Pandoc issue. The installed version produced a flat approximation instead of the placeholder reported there. That approximation kept the later cells in position, but it still replaced the merge with an empty field. ⁷⁸

Repair field meaning before accepting a rendered table

A successful render proves that the reader recognized a table; the headings and cell content still need to describe the source records.

For the spanning-category example, an explicit rewrite can repeat East beside each item. The category then travels with the record if the rows are separated. An empty category position can retain the visual grouping in a nearby table, but a detached row would lack its category. Editorial rewrite, not converter output:

| Group | Item | Qty |
        | --- | --- | --- |
        | East | Apples | 12 |
        | East | Pears | 9 |
        

Combine the parent and leaf labels, such as Quarter / Units and Quarter / Returns, into distinct flat fields. Leaving an unnamed column beside the parent label does not tell a reader which measurement it contains. Keep the original HTML if the hierarchy itself must remain visible. ²

Both converters emitted an unescaped pipe inside an inline code expression. The table readers split that expression into separate cells, then discarded the link beyond the width declared by the header. The saved Markdown still contained the link, while the parsed table did not. ⁸

Output from our inline-code sample, unedited:

| Expression | Reference |
        | --- | --- |
        | `a|b` | [docs](https://example.com/docs) |
        

Escape the literal pipe inside that cell as a\|b, keeping the code-span backticks around it. Our edited input restored the code expression and its neighboring link in both table readers. Apply the escape to a data pipe, not every pipe in the document: the others delimit cells. ⁸

markdown-it-py's table rule separates cells before parsing their inline content. It recognizes an escaped pipe during that split, then parses the code and link within the resulting cells. The header fixes the output width, so an extra apparent cell can disappear without a table-level error. ⁹

The ordinary grid appeared as a paragraph in our CommonMark-only reader and as a table after enabling its table rule. The merged-category and inline-code failures remained visible in the readers that did support tables. ⁸

These checks also apply when cleaning exported Markdown after Markovo's public-page conversion. That upstream route is listed as Signed-in Beta for publicly accessible HTTPS pages. We did not test the service on this table-fragment corpus. ¹⁰

Use flat Markdown fields for records whose relationships are explicit. Preserve HTML when spans or internal blocks carry meaning. When HTML is unavailable, rewrite those relationships into headings and repeated values before exporting, then inspect the first affected record and any cell containing a data pipe.

How we tested

This guide tests local conversion and parsing behavior on synthetic fragments, not GitHub.com, VS Code, browser layout, CSS fidelity, accessibility, or live webpage extraction. Markovo did not run this table-fragment corpus. Upstream PDF and Office results were excluded. No OCR scoring or performance benchmark was performed.

The conversion and readback date was 2026-10-20. We used markdownify 1.2.3 with Beautiful Soup 4.15.0, Pandoc 3.11, and markdown-it-py 4.0.0. Both Python environments used Python 3.11.14. ⁸

The reproduction script contains the complete inputs and commands. HTML inputs and raw HTML outputs are stored as .txt for publication. ¹¹

Run from the repository root with the existing environments. The script makes no network calls:

.venv/bin/python runs/2026-10-20-markovo-html-table-to-markdown/lab/table_roundtrip.py
        

The Python converter uses tools/lab-venv/bin/python, bs4_options="html.parser", and table_infer_header=False. The article's Python example is saved verbatim in convert_example.py. Both article commands were executed from the run's lab/example/ directory with the simple input copied to input.html. Their outputs and exit codes are retained in the execution record. ¹⁴

cd runs/2026-10-20-markovo-html-table-to-markdown/lab/example
        cp ../renderers/simple.input.txt input.html
        ../../../../tools/lab-venv/bin/python ../convert_example.py
        pandoc -f html -t gfm --wrap=none input.html -o output.md
        

The corpus command converts each input with markdownify and with pandoc -f html -t gfm --wrap=none. It reads each resulting Markdown file through MarkdownIt("commonmark", {"html": True}), the same reader with .enable("table"), and pandoc -f gfm -t html --wrap=none. The first reader is a control without the table rule. ⁸¹¹

“Tables CM/T/P” counts <table> elements in CommonMark-only markdown-it-py, markdown-it-py with its table rule, and Pandoc GFM readback, respectively. The remaining columns are tag counts from the markdown-it-py table-enabled readback: rows (tr), heading cells (th), data cells (td), breaks (br), and list items (li). These are physical elements, not a score for correct field associations. A raw HTML rowspan can occupy multiple slots while still being a single td. Each result also stores the cell text and attributes. ⁸

Counts alone miss the inline-code failure: both converters' inline output produced no code or a element in either table-enabled reader. The edited inline-repaired.md produced a code element and a link in each reader. The edited rowspan-repaired.md kept the category beside each item. These edited files are labeled editorial-rewrite in the report. They are not converter outputs. ⁸

The exact table from markdownify issue 121 was rerun with the installed version. Its short final row remained. The leftmost-span sample is a separate diagnostic variation, not the issue author's original input. Pandoc issue 11128 was also rerun with its reported writer configuration: ⁶⁷

pandoc -f html -t markdown_strict+pipe_tables-raw_html --wrap=none \
          runs/2026-10-20-markovo-html-table-to-markdown/lab/renderers/issue-11128.input.txt
        

The saved forced-pipe output contains an empty field before Theory. The installed Pandoc version did not reproduce the reported [TABLE] placeholder on that input. ⁷⁸

The installed markdownify source records convert_tr, convert_td, convert_th, and convert_br. The installed parser source records escapedSplit and table. The former handles spans within a row without carrying rowspan occupancy forward. The latter fixes the column count from the header, fills absent cells with empty content, and splits cells before inline parsing. ¹²¹³

Original conversion files follow lab/renderers/<sample>--markdownify.md and <sample>--pandoc-gfm.md. Raw readbacks follow <sample>--<converter>--<reader>.txt. The report records conversion commands and Markdown output hashes, plus readback paths, cell text, and attributes in results.json. The summary does not use tools/lab_score.py: that script defines PDF extraction metrics, while this experiment measures Markdown/HTML structure. ⁸¹¹

Sources

1. GFM specification: tables extension
2. HTML Standard: table processing model
3. markdownify README, version 1.2.3
4. markdownify source, version 1.2.3
5. Pandoc manual: pipe tables
6. markdownify issue 121: rowspan support
7. Pandoc issue 11128: HTML colspan conversion
8. Local conversion and renderer results
9. markdown-it-py table rule, version 4.0.0
10. Markovo product-scope snapshot
11. Reproduction script and complete synthetic inputs
12. Installed markdownify table-handling source
13. Installed markdown-it-py table parser source
14. Executed article examples