HTML table conversion guide

Convert simple HTML tables—and redesign the complex ones

GFM pipe tables work well for a rectangular grid with one header row and one line of text per cell. Merged cells, nested structures, and layout tables need a different decision.

Open MD Studio See a conversion

A table fits Markdown when its meaning is already tabular

Use a GFM table for comparable records with stable columns. Use headings, lists, or retained safe HTML when the source relies on spans, nested content, or visual placement instead of a simple grid.

A clean rectangular example

HTML

<table>
  <thead>
    <tr><th>Page</th><th>Status</th></tr>
  </thead>
  <tbody>
    <tr><td>Install</td><td>Ready</td></tr>
    <tr><td>Upgrade</td><td>Review</td></tr>
  </tbody>
</table>

GFM

| Page | Status |
| --- | --- |
| Install | Ready |
| Upgrade | Review |

The GFM table extension defines a header row, delimiter row, and data rows. CommonMark does not include this pipe-table extension.

A reliable conversion workflow

Inspect the source.Identify header cells, data rows, alignment, spans, multiline cells, and nested content.
Convert to GFM.Paste or import the HTML, keeping the GFM profile selected for pipe-table output.
Test the destination.Verify escaped pipes, column count, alignment, line breaks, and the renderer that will publish it.

Structures that need a decision

HTML feature	Why it is difficult	Practical response
`rowspan` or `colspan`	Pipe tables have no equivalent merged-cell model	Repeat labels, split the table, or retain reviewed HTML
Multiple paragraphs in a cell	Ordinary line breaks can end the row	Condense, use safe inline breaks where supported, or redesign
Lists or code blocks in cells	Block content is not portable in pipe tables	Move detail below the table or use headings and lists
Nested tables	The structure cannot map cleanly to one grid	Flatten into separate sections or tables
Layout-only table	Columns express placement rather than comparable data	Replace with semantic headings, paragraphs, or lists

Table review checklist

Every row has the intended number of columns.
Literal pipe characters inside cells are escaped.
Header labels describe the comparison dimension.
Alignment is meaningful and supported by the destination.
Empty cells are intentional rather than conversion loss.
Links and inline code remain intact.
The table is readable on a narrow screen.

A large table can be valid Markdown and still be a poor reading experience. Splitting it may be the better conversion.

HTML-table FAQ

Do CommonMark renderers support pipe tables?

Not as part of the CommonMark core specification. Some products add their own table extension, so check the actual renderer.

Will MD Studio keep a complex table perfectly?

No converter can represent HTML table spans and arbitrary block content in ordinary GFM pipe syntax without tradeoffs. Review and redesign may be required.

Can I retain raw HTML instead?

Some Markdown destinations allow raw HTML and others remove or escape it. MD Studio sanitizes rendered output; test the final destination and its security policy.

Test the hardest row first

Convert the row with a span, nested list, link, or multiline cell before committing to the whole table.

Open MD Studio