How to use the html table to markdown converter
- Paste your HTML table markup into the input area.
- The tool parses
<thead>for headers and<tbody>for data rows automatically. - Review the generated GFM markdown table in the output area.
- Copy the result and paste it into your README, wiki or documentation file.
How the conversion works
The tool reads the HTML text, builds a small element tree and walks the rows without relying on a browser DOM. Rows in <thead>, <tbody>, <tfoot> or placed directly inside <table> are all read, and optional closing tags such as a missing </td> are handled the way a browser would. Each cell becomes one line of Markdown: <b> becomes **bold**, <i> becomes *italic*, <code> becomes backticks, links become [text](url), images become  and line breaks become <br>. Literal pipe characters (|) are escaped as \| so they do not break the table.
The header row is the thead row when there is one. Without a thead the first row is used as the header, and a note tells you so. Alignment is detected from style="text-align:..." or the legacy align="..." attribute. Left alignment produces :---, center produces :---:, right produces ---:, and no alignment defaults to ---.
For example, given this source:
<th style="text-align:center">Qty</th>
The resulting separator row for that column becomes :---:, which tells any GFM renderer to center the column contents.
Alignment reference
GFM tables support three alignment options plus a default. Here is how each HTML attribute maps to the markdown separator syntax when you perform an html table to markdown conversion:
| HTML attribute | Separator | Effect |
|---|---|---|
style="text-align:left" or align="left" | :--- | Left-aligned column |
style="text-align:center" or align="center" | :---: | Centered column |
style="text-align:right" or align="right" | ---: | Right-aligned column |
| (none) | --- | Default (usually left) |
If your source uses inline styles with extra whitespace like text-align : center, the parser normalizes it before matching. This ensures consistent markdown table alignment regardless of how the original author formatted the CSS.
Handling colspan and merged cells
GitHub Flavored Markdown does not support merged cells. When the parser encounters a colspan attribute greater than 1, it places the cell content in the first column and fills the remaining spanned columns with empty cells. A rowspan works the same way downwards: the text stays in the first row and the rows below get empty cells so the columns stay aligned. A note below the table tells you when merged cells were found.
If your source table relies heavily on merged headers or spanning cells, consider restructuring it before converting. For building fresh tables from scratch, a markdown table generator can help you create clean layouts directly without worrying about unsupported features.
Escaping special characters
Pipe characters inside cell content must be escaped, otherwise the Markdown parser treats them as column boundaries. This tool replaces every | with \| automatically, including inside code spans. Line breaks inside a cell become <br> and other whitespace collapses to single spaces because GFM tables cannot hold multi-line cells.
Characters that Markdown treats as formatting, such as *, _, backticks and square brackets, are escaped with a backslash when they are plain text in the HTML, so they appear literally in the rendered table. Named entities like & and and numeric entities are decoded to real characters.
If you need to handle other markup conversions, such as going the opposite direction, the markdown to html tool covers that workflow. For broader document transformations, see the general html to markdown page.
When to use this tool
Documentation workflows frequently require switching between formats. You might receive tabular data as HTML from a CMS export, a web scraper or an email template and need it in a README.md file. This html table to markdown converter handles that step without installing packages or running scripts.
It is also useful when migrating wikis. If you previously used an html table generator to build documentation pages and now want to move to a Git-based wiki, pasting the source through this tool gives you ready-to-commit GFM output.
Developers working with API responses that return HTML fragments can quickly transform those fragments into readable markdown for internal notes or issue tracker comments. The entire process happens locally in your browser, making it safe for proprietary data.
Worked examples
| Example | Input | Result |
|---|---|---|
| Basic two-column table | HTML table: <table><thead><tr><th>Name</th><th>Role</th></tr></thead><tbody><tr><td>Alice</td><td>Admin</td></tr><tr><td>Bob</td><td>User</td></tr></tbody></table> | | Name | Role | / | --- | --- | / | Alice | Admin | / | Bob | User | |
| Table with alignment | HTML table: <table><thead><tr><th style="text-align:left">Item</th><th align="center">Qty</th><th style="text-align:right">Price</th></tr></thead><tbody><tr><td>Widget</td><td>5</td><td>$9.99</td></tr></tbody></table> | | Item | Qty | Price | / | :--- | :---: | ---: | / | Widget | 5 | $9.99 | |
| Cells containing pipes | HTML table: <table><thead><tr><th>Expression</th><th>Result</th></tr></thead><tbody><tr><td>a || b</td><td>true | false</td></tr></tbody></table> | | Expression | Result | / | --- | --- | / | a \|\| b | true \| false | |
FAQ
Does this handle nested tables?
Not as separate tables. A table inside a cell is flattened to its text, because GFM tables cannot nest. Tables that follow each other in the page are each converted.
What happens if my HTML has no thead element?
The first row is used as the header, since a GFM table always needs one, and a note under the output tells you that. If the first row is made of th cells it is the header anyway.
Are pipe characters inside cells handled correctly?
Yes. Every literal pipe character in cell text is escaped with a backslash so the resulting html table to markdown table output renders properly in any GFM-compatible viewer.
Can I convert multiple tables at once?
Yes. If your HTML contains several table elements, each one is converted in order and the Markdown tables are separated by a blank line.
Is any data sent to a server?
No. The parsing logic runs entirely in your browser using JavaScript. Your HTML source never leaves your machine.
How is column alignment determined?
The parser checks each cell for a style attribute containing text-align or a legacy align attribute. For each column it uses the first cell that has an alignment, starting with the header. left, center and right map to the matching GFM separator syntax.