DOCX to Markdown with Tables: The Complete Guide

Tables are one of the trickiest elements when converting Word documents to Markdown. This guide shows you exactly how table conversion works and how to get the best results.

How Word Tables Become Markdown Tables

Markdown (specifically GitHub Flavored Markdown or GFM) supports tables using pipe characters:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

When you convert a Word document, the table’s first row (if styled as a header row) becomes the GFM table header, with a separator line of dashes beneath it.

Table Structures That Convert Well

Simple data tables with a header row and consistent columns convert perfectly:

Known Limitations

Merged cells — When Word cells span multiple columns or rows (colspan/rowspan), there’s no Markdown equivalent. The converter will output the cell content without the spanning, which may cause misaligned columns.

Nested tables — Tables inside tables are flattened to their text content.

Complex formatting — Bold, italic, and inline code within table cells are preserved, but complex embedded content may be simplified.

Tips for Table-Heavy Documents

1. Avoid merged cells when possible — split them before converting
2. Use header row styling in Word — right-click the first row and mark it as a header row for best results
3. Keep column counts consistent — every row must have the same number of cells for valid GFM tables
4. Review after conversion — always check table output in a Markdown preview before publishing

Rendering Markdown Tables

Once you have your Markdown table, it renders properly in:

• GitHub (README files, issues, PRs)
• GitLab
• Notion
• Obsidian
• Most static site generators (Jekyll, Hugo, Astro)
• VS Code Markdown preview

Give it a try with WordToMD’s free converter — just drag and drop your .docx file and see your tables rendered as clean GFM Markdown instantly.