More guides
Tables in Markdown
Tables are where most documents break when an AI reads them. Here's how to write them so the structure survives, and how to spot a table that's been flattened into noise.
~4 min read
GFM
Updated Jun 2026
Basic syntax
A table is just pipes and dashes: a header row, a divider of hyphens, then your data. Colons in the divider set column alignment.
markdown
| Metric | Q2 | Q3 | |:----------|-----:|-----:| | Retention | 91% | 95% | | Churn | 2.4% | 2.1% |
:--- left · ---: right · :--: center
Rendered result
| Metric | Q2 | Q3 |
|---|---|---|
| Retention | 91% | 95% |
| Churn | 2.4% | 2.1% |
Why AI reads it better
When the pipes line up, a language model parses rows and columns as real relationships. Flatten the same data into prose and the model has to guess which number belongs to which metric.
Tip. Keep one fact per cell. Merged cells and multi-line cells are the most common cause of tables collapsing during conversion.
Not ideal for: deeply nested or spanned tables. If your source has merged header cells, expect even good tools to need a manual pass — see the PDF tables benchmark.