SwitchPDF
All articles
Developer July 5, 2026 3 min read

Writing Markdown Tables That Convert Cleanly to Word

Markdown tables look easy but break in subtle ways during conversion. Here's how to write ones that come out looking professional in Word.

Markdown tables are straightforward in concept but the conversion to Word breaks in non-obvious ways. Here's how to write tables that come out clean.

The basic syntax

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1A   | Row 1B   | Row 1C   |
| Row 2A   | Row 2B   | Row 2C   |

That converts to a real Word table with three columns and three rows.

Alignment

Add colons in the separator row:

| Left | Center | Right |
|:-----|:------:|------:|
| a    |   b    |     c |
  • :--- = left
  • :---: = center
  • ---: = right

Pandoc respects these in the Word output.

Where tables break

Inconsistent column counts

| A | B | C |
|---|---|---|
| 1 | 2 |
| 3 | 4 | 5 | 6 |

Rows have 2, 4 columns when the header has 3. The conversion may produce ragged rows or skip the table entirely. Fix: make every row have exactly N columns.

Pipes inside cells

If your cell value contains a pipe character (|), it confuses the parser:

| Column | Cell containing | a pipe |

Escape it with backslash: \|

| Column | Cell containing \| a pipe |

Multi-line cell content

Markdown tables don't support multi-line cells (line breaks within a cell). If you need a cell to have a newline, use <br>:

| Header | Content |
|--------|---------|
| Notes  | First line<br>Second line |

The <br> survives the conversion to Word.

Very wide tables

If your table has 10+ columns, the Word output won't fit a portrait page. Either:

  • Set the Word page to landscape after conversion
  • Split the table into multiple narrower tables
  • Restructure the data (transpose rows and columns)

Cell formatting

Inline Markdown formatting works inside cells:

| Status | Action |
|--------|--------|
| **Critical** | Fix *now* |
| Warning | Review by `Friday` |

Bold, italic, and inline code all convert correctly.

When to use tables

  • Comparing options across multiple attributes
  • Listing structured data (parameters, settings, etc.)
  • Reference material (status codes, error messages, command flags)

Don't use tables for:

  • Free-flowing text that just happens to have a few common headings — use headings instead
  • Layout purposes (forcing two columns of text side-by-side) — tables are for data, not layout

Testing your table

Always preview the rendered table before converting. In SwitchPDF Markdown to DOCX, the live preview shows the table as Pandoc will produce it. If it looks broken in the preview, fix the source before converting.

Bottom line

Stick to consistent column counts, escape pipes inside cells, use <br> for multi-line content, and preview before converting. Tables are powerful when the source is clean.

Related articles