Markdown Tables: A Complete Guide to GFM Table Syntax

Markdown tables let you display structured data in a readable format that renders as an HTML table. This guide covers the complete GFM (GitHub Flavored Markdown) table syntax, alignment options, advanced patterns, and how to convert Word tables to Markdown.

Basic Table Syntax

A Markdown table has three parts:

1. Header row — column names
2. Separator row — dashes with pipes, defines the table
3. Data rows — the content

| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |

Renders as:

Column Alignment

Use colons in the separator row to control alignment:

| Left aligned | Center aligned | Right aligned |
|:---|:---:|---:|
| text | text | text |
| longer text | longer text | longer text |

• :--- — Left align (default)
• :---: — Center align
• ---: — Right align

Formatting Inside Table Cells

Most inline Markdown formatting works inside table cells:

| Element | Example |
|---|---|
| Bold | **bold text** |
| Italic | *italic text* |
| Code | `inline code` |
| Link | [click here](https://wordtomd.com) |
| Strikethrough | ~~deleted~~ |

What doesn’t work: multi-line content, nested lists, block-level elements.

Pipe Characters in Cells

If you need a literal pipe | inside a cell, escape it with a backslash:

| Flag | Description |
|---|---|
| `x \| y` | Bitwise OR operator |

Tables Without Spacing

Spacing around pipes is optional. This is valid:

|Column 1|Column 2|
|---|---|
|Cell|Cell|

But consistent spacing makes tables more readable. Most editors and linters prefer the spaced format.

Empty Cells

Leave the space between pipes empty for an empty cell:

| A | B | C |
|---|---|---|
| content | | content |
| | content | |

Converting Word Tables to Markdown

Word tables convert automatically when you use WordToMD. The converter handles:

• Standard grids → GFM pipe tables
• Column widths → standardized (Markdown doesn’t control column width)
• Text formatting inside cells → preserved (bold, italic, links)

What doesn’t convert:

• Merged cells (colspan/rowspan) — collapsed to nearest cell
• Multi-line cell content — line breaks stripped
• Nested tables — inner table flattened

Handling Complex Word Tables

Merged Cells

Word’s merged cells have no Markdown equivalent. Options:

1. Restructure — Split merged rows into separate tables
2. Use HTML — Most Markdown processors accept HTML table syntax:

<table>
  <tr>
    <th colspan="2">Merged Header</th>
  </tr>
  <tr>
    <td>Cell 1</td>
    <td>Cell 2</td>
  </tr>
</table>

Multi-line Cell Content

Use <br> for line breaks inside cells (works on GitHub and most platforms):

| Step | Description |
|---|---|
| 1 | Open the file<br>Make sure it's .docx format |
| 2 | Drop it on [WordToMD](/#converter) |

Large Tables

For tables with many columns, consider whether a table is the right format. Alternatives:

• A definition list (term + description)
• Multiple smaller tables by category
• A code block for structured data (JSON, YAML)

Table Rendering by Platform

Accessibility

For better accessibility, ensure tables have a header row with meaningful column names. Screen readers use the header row to announce cell context.

| Product | Price | Availability |
|---|---|---|
| Widget A | $9.99 | In stock |
| Widget B | $14.99 | Out of stock |

Avoid using tables for layout purposes — use them only for actual tabular data.

FAQ

Why isn’t my table rendering — it shows as plain text? The separator row (the |---|---| line) is mandatory. Without it, the parser won’t recognize the table structure.

Can I have a table without a header row? Not in standard GFM. The header row and separator are required. If you don’t want a visible header, use a blank header: | | | with a separator row.

Why do my tables from Word look right in WordToMD but wrong after I paste them elsewhere? The issue is usually trailing whitespace in cells or inconsistent pipe characters. Most Markdown renderers are lenient, but copy-paste can introduce invisible characters.

How do I create a table programmatically from data? Libraries like markdown-table (npm) or Python’s tabulate can generate Markdown tables from arrays. This is useful for batch-converting CSV or database data.

Related Guides

• What Is Markdown? — Markdown basics
• Markdown Syntax Cheat Sheet — Full syntax reference
• How to Convert Word to Markdown — Full conversion guide
• DOCX to Markdown with Tables — Focused on table conversion

Conclusion

Markdown tables are powerful for displaying structured data and are widely supported across all major platforms. For tables that start in Word, WordToMD converts them automatically to GFM syntax. For complex layouts, the HTML fallback and the tricks above give you the control you need.