Why Your Markdown Tables Break in Word (And How to Fix It)

You have a clean Markdown table — headers aligned, pipes in all the right places, renders perfectly in your editor or on GitHub. You convert it to Word. You open the .docx file. And instead of a formatted table, you're staring at one of three things: a wall of raw <table><tr><td> HTML tags, a single line of pipe characters running across the page, or something that looks like a table but has no borders and falls apart the moment you click on it.

This is one of the most common failures in Markdown-to-Word conversion, and it happens because of a specific flaw in how most converters work under the hood.

The HTML Middleman Problem

Most Markdown-to-Word converters don't actually convert Markdown to Word format directly. They convert Markdown to HTML first — using a parser like Marked, Showdown, or a custom implementation — and then try to inject that HTML into a Word document using a library like html-docx-js.

The pipeline looks roughly like this:

Parse Markdown source into an HTML string
Wrap that HTML in a basic Word template
Save the result as a .docx file

The problem is in step 2. Libraries like html-docx-js don't actually translate HTML elements into native Word XML. They embed the HTML as-is inside the document container and rely on Word to render it. Word's HTML rendering engine is limited, inconsistent across versions, and completely unable to handle complex table structures the way a browser would. Older versions of Word (2013, 2016) often refuse to render embedded HTML tables at all and display the raw markup instead. Newer versions may render something, but it won't behave like a real Word table.

This is fundamentally different from how Word actually stores tables. Word uses Office Open XML (OOXML) — a structured XML schema where every table, row, cell, and border is defined with specific tags like <w:tbl>, <w:tr>, <w:tc>. A table produced by the HTML middleman approach is not a <w:tbl>. It's an HTML blob that Word is grudgingly trying to display.

What Broken Output Actually Looks Like

Raw HTML tags in the document

The most obvious failure: you open the .docx and see literal HTML. Something like:

<table><thead><tr><th>Name</th><th>Role</th><th>Status</th></tr></thead><tbody><tr><td>Alice</td><td>Engineer</td><td>Active</td></tr></tbody></table>

This happens when Word's HTML renderer fails entirely and the embedded string gets treated as plain text. The Markdown was converted to HTML correctly — the problem is that the HTML never became a Word document element.

Pipe characters on a single line

Your source Markdown table looks like this:

| Name  | Role      | Status |
|-------|-----------|--------|
| Alice | Engineer  | Active |
| Bob   | Designer  | Active |
| Carol | PM        | On leave |

But in Word, you get:

| Name | Role | Status | | ----- | --------- | ------ | | Alice | Engineer | Active | ...

Everything collapsed onto one line, separators included. This happens when the converter strips the HTML but falls back to the raw Markdown text, which Word renders as a single paragraph. No table structure survives.

A table with no borders

Sometimes the conversion half-works. You get something that looks like a table — cells in roughly the right positions — but there are no grid lines, no header shading, and the column widths are either uniform or completely wrong. Click on a cell and you'll find it's not actually a Word table at all. You can't add rows, apply Table Design styles, or sort columns. It's a visual approximation with no real structure underneath.

What Correct Output Looks Like

A proper Word table produced from a Markdown source should be indistinguishable from one you built inside Word manually. That means:

A native <w:tbl> element in the document XML, not embedded HTML
Borders on every cell — top, bottom, left, right, and interior grid lines — defined as <w:tcBorders> with explicit border style, size, and color
A header row with background shading (<w:shd>) so the column labels stand out visually
Column widths distributed sensibly across the page width, not all squeezed to minimum or stretched to maximum
Full editability: click into any cell, tab between cells, right-click to add rows above or below, apply built-in Table Design styles from the Word ribbon

The key indicator is behavior, not appearance. If you can interact with the table the same way you would with one created natively in Word, the conversion worked. If clicking on it feels like clicking on a picture or a text block, it didn't.

The Fix: Direct AST-to-OOXML Mapping

The right approach skips the HTML middleman entirely.

Instead of Markdown → HTML string → Word, the correct pipeline is:

Parse the Markdown source into an abstract syntax tree (AST)
Walk the AST and identify table nodes — the list of headers, the separator row, and each data row
Construct native Word table XML directly from that structured data

Step 3 is where it matters. Using a library like docx (the JavaScript library for programmatic Word document creation), you can build a real Table object with TableRow and TableCell instances, set explicit BorderStyle values on every cell, apply shading to the header row, and calculate column widths based on the page dimensions. The output is a genuine OOXML table that Word treats exactly like any other table in the document.

There's no HTML involved. The converter never produces an HTML string for the table at all — it maps the parsed Markdown structure directly to Word XML. This is how mdtowordconverter.com handles table conversion, which is why the tables it produces are fully editable and correctly formatted across all Word versions.

For more on how different Markdown elements map to Word formatting, the Markdown syntax to Word formatting reference covers the full element set, including heading styles, code blocks, and lists.

Quick Workarounds If You're Stuck With a Broken Converter

If you're using a converter you can't replace and it's mangling your tables, here are two workarounds that sometimes salvage the situation.

Convert text to table in Word. If the pipe character structure survived in the output (scenario 2 above), select the affected text in Word, go to Insert → Table → Convert Text to Table, and set the separator character to other with a pipe (|). Word will attempt to rebuild the table from the delimiters. The result needs cleanup but can be faster than starting over.

Use Google Sheets as a bridge. Paste your Markdown table into a text editor, strip the separator row (the |---|---| line), and paste the remaining rows into Google Sheets — one row per line, using the pipe character as a delimiter (File → Import with custom separator). Once the data is in Sheets, copy the cell range and paste it into Word. Word accepts spreadsheet paste data as a native table with borders and proper cell structure.

Both approaches are workarounds with real limitations. They require manual cleanup, don't handle merged cells, and fall apart with complex table structures. They're reasonable for a one-off fix, not a repeatable workflow.

Get Tables That Just Work

If you're regularly converting Markdown documents that contain tables, the only reliable solution is a converter that uses direct OOXML generation rather than the HTML middleman approach. You shouldn't have to manually repair table formatting after every conversion.

mdtowordconverter.com converts Markdown tables to native Word tables — borders, header shading, editable cells, correct column widths — without any intermediate HTML step. Paste your Markdown, download the .docx, open it in Word, and the table is ready to use.

If table formatting is one part of a broader conversion problem you're working through, how to convert Markdown to Word without losing formatting covers the wider set of issues and how to avoid them.