Convert Word Tables to Markdown: The Complete Guide
Tables are where Word→Markdown conversion gets ugly. Simple grids — fixed columns, plain text in each cell, one header row — convert flawlessly with any tool. Anything more complex (merged cells, multi-row headers, nested tables, cells with images, cells with paragraph breaks) bends or breaks. The reason is structural: GitHub-Flavored Markdown's pipe-table syntax was designed for the 80% case, not the long tail. This guide walks through what survives, what doesn't, and the manual tactics that work when conversion alone isn't enough.
What GFM tables can represent
The pipe-table syntax in GitHub-Flavored Markdown (and basically every modern Markdown flavour) supports:
- Fixed number of columns
- One header row
- One row of alignment markers (
:--,:-:,--:) - Plain text or simple inline formatting (bold, italic, code, links) in each cell
That's it. There's no syntax for merged cells, multi-row headers, nested tables, captions, footnotes per cell, or block-level content (paragraphs, lists, code blocks) inside cells. Any of those need workarounds.
The simple case: clean conversion
A standard Word table — say a 4-column "Feature comparison" with one header row and 10 data rows of plain text — converts to GFM perfectly with any tool. Drop the .docx in the MDisBetter Word to Markdown converter:
| Feature | Free | Pro | Enterprise |
| ------------ | ---- | ---- | ---------- |
| Conversions | 5/mo | 100 | Unlimited |
| File size | 5MB | 50MB | 500MB |
| OCR | No | Yes | Yes |
| Support | None | Email| Phone |Renders correctly everywhere, no manual cleanup required.
Merged cells
Word's merged cells (vertically or horizontally combined cells in a table) have no GFM equivalent. The conversion picks one of three strategies:
Strategy 1: Repeat the value
If you merged 3 horizontal cells with "Q1 2026", the conversion repeats: | Q1 2026 | Q1 2026 | Q1 2026 |. Visually misleading, but the data is preserved.
Strategy 2: Empty the merged cells
The first cell keeps the value, the others become empty: | Q1 2026 | | |. Better for data integrity but visually confusing.
Strategy 3: Drop the table
Some converters skip the table entirely if it has merged cells. Worst outcome.
The MDisBetter web tool uses Strategy 2 (empty merged cells with the value in the first). Pandoc uses Strategy 1 (repeat the value). Mammoth.js varies.
Manual fix for merged cells
If the table is critical, restructure it. Two tactics:
Convert horizontal merges to grouped headers using bold:
**Q1 2026**
| Region | Sales | Forecast |
| ------ | ----- | -------- |
| EMEA | 100 | 120 |
| AMER | 200 | 220 |Split into multiple tables: If a Word table had a merged "Section A" header spanning 5 columns then "Section B" spanning 5 columns, split it into two side-by-side or sequential tables.
Multi-row headers
Word frequently has tables with two header rows: top row is a category, second row is the column name. GFM supports exactly one header row.
Conversion result: usually the first row becomes the GFM header row and the second row becomes a regular data row. Looks broken.
Manual fix
Combine the two header rows into one with a separator. Original:
| Sales | | Marketing | |
| Q1 | Q2 | Q1 | Q2 |Becomes:
| Sales Q1 | Sales Q2 | Marketing Q1 | Marketing Q2 |
| -------- | -------- | ------------ | ------------ |Cells with paragraph breaks
Word allows multiple paragraphs (or even bullet lists) inside a single cell. GFM cells are single-line.
The conversion typically replaces the paragraph break with <br>:
| Notes |
| ----- |
| Line one<br>Line two<br>Line three |Renders correctly in HTML-aware Markdown environments (GitHub, MkDocs, Obsidian) but ugly to read in raw Markdown.
Cells with bullet lists
Bullets inside a table cell don't have a clean GFM representation. Common conversion: collapsed to comma-separated text or rendered with <br>- item patterns. Often loses the visual list.
Manual fix
Replace the table with a definition list:
**Authentication options**
: - OAuth 2.0
- API keys
- Magic link
**Logging options**
: - JSON
- Plain text
- SyslogOr just promote each row to a section heading with a sub-list. More verbose but readable.
Nested tables (table inside a cell)
Word allows tables inside cells of other tables. GFM doesn't support this at all. Conversion either flattens the nested table to text or drops it.
Manual fix
Refactor into multiple sequential tables, with explicit headings to make the relationship clear. There's no shortcut.
Cells with images
Word can place images inside table cells. GFM cells can technically include image syntax (), but the resulting Markdown is fragile and rendering varies by environment. Most renderers display the image inline in the cell, which works for icons and small thumbnails but breaks for larger images.
If your Word doc has tables full of inline images (e.g., a screenshot per row in a step-by-step guide), consider converting to a numbered list with images between each item:
1. Click the gear icon
2. Select Profile
Tables with captions
Word table captions become normal paragraphs after conversion — usually placed before or after the table without any structural marker. To restore the caption-table relationship, prefix with Table N::
**Table 3: Quarterly revenue by region**
| Region | Q1 | Q2 | Q3 | Q4 |
| ------ | --- | --- | --- | --- |
| EMEA | 100 | 110 | 115 | 120 |Very wide tables
Tables with 8+ columns become unreadable in raw Markdown (very long lines) and often overflow on mobile. Three workarounds:
Split horizontally
Split a 12-column table into two 6-column tables with a shared key column.
Pivot to rows
If the table has 5 rows and 12 columns, transpose it to 12 rows and 5 columns. Often more readable.
Convert to a definition list
For tables that are really structured records (one row per item with a fixed set of attributes), a definition list reads better:
## Item ABC-123
- **SKU**: ABC-123
- **Price**: $19.99
- **Stock**: 247
- **Category**: Widgets
- **Supplier**: AcmeComparison: which converter handles tables best
| Tool | Simple tables | Merged cells | Multi-row headers | Nested tables |
|---|---|---|---|---|
| MDisBetter web | Excellent | Empty merged cells | Treats as data row | Flattens to text |
| Pandoc | Excellent | Repeats value | Treats as data row | Flattens to text |
| Mammoth.js | Good | Variable | Variable | Often dropped |
| Word HTML export → MD | Poor (bloated HTML) | Bloated | Bloated | Sometimes preserved as HTML table |
For more on choosing a converter, see the 8-tool benchmark and MDisBetter vs Pandoc.
Pre-conversion: simplify in Word first
If you control the Word doc, the easiest fix is to simplify before converting:
- Unmerge cells where possible
- Flatten multi-row headers into single-row headers
- Remove nested tables
- Replace cell-internal bullet lists with bold-tagged inline lists or split rows
Five minutes of Word editing saves an hour of post-conversion cleanup.
Post-conversion: HTML escape hatch
Most Markdown processors (including GitHub, MkDocs Material, Obsidian) render raw HTML inline. If a table is too complex for GFM, write it as raw HTML:
<table>
<thead>
<tr>
<th rowspan="2">Region</th>
<th colspan="2">2025</th>
<th colspan="2">2026</th>
</tr>
<tr>
<th>Q1</th><th>Q2</th><th>Q1</th><th>Q2</th>
</tr>
</thead>
<tbody>
<tr><td>EMEA</td><td>100</td><td>110</td><td>115</td><td>120</td></tr>
</tbody>
</table>Renders perfectly with rowspan and colspan. Tradeoff: less portable (some Markdown renderers strip HTML), uglier source. But for the table you absolutely need to preserve, it's the right escape hatch.
When to skip the table entirely
Sometimes the most honest answer is to drop the table. If your Word table was a layout artifact (using a 1-cell, no-border table to constrain text width, for example), there's nothing to preserve. Convert to plain paragraphs.
Spreadsheet-style data: use CSV instead
If your Word table is really tabular data with 50+ rows that someone might want to filter or sort, the right answer isn't Markdown at all — it's CSV. Extract the table as a separate data.csv file and reference it from the Markdown:
## Quarterly Revenue
Full data: [revenue.csv](./data/revenue.csv)
| Region | Q1 | Q2 | Q3 | Q4 |
| ------ | --- | --- | --- | --- |
| EMEA | 100 | 110 | 115 | 120 |
| AMER | 200 | 220 | 230 | 245 |Show a small preview in Markdown, link to the full data. Better for everyone.
Tables in destinations
The destination matters too. Tables that survive conversion may render differently:
- GitHub: GFM tables render natively, very widely supported
- Obsidian: GFM tables render; the Advanced Tables plugin makes editing easier
- Notion: Markdown table import creates a Notion table block (full editing support)
- MkDocs: GFM tables render with the
tablesmarkdown extension enabled - VS Code preview: GFM tables render natively
Recommendation
For most Word documents, run the .docx through the web tool, accept that simple tables will be perfect and complex ones will need 5-15 minutes of cleanup. Use the manual fixes above for the tables that matter; consider raw HTML as the escape hatch for the truly complex ones; convert really-tabular-data to .csv. For more cross-tool comparison see formatting preservation accuracy test.