Markdown Table vs CSV in Docs — Not Interchangeable

A PM asks to “put the CSV in the README so people can Excel it.” Someone pastes thirty columns of commas into a fenced code block. Someone else converts to a Markdown table that wraps into unreadability on mobile. Both formats store grids — they are not interchangeable media for documentation. Choosing wrong wastes review time and trains readers to ignore the docs.

What each format optimizes

	Markdown table	CSV
README / PR / Notion	Renders as a table	Shows as raw text unless linked
Excel / Sheets	Copy-paste awkward	Native open
Diffs in git	Painful for wide tables	Line-oriented, still noisy
Cell with | or commas	Escaping / breaks layout	Comma rules / quoting
Narrative docs	Excellent for 3–8 columns	Better as downloadable artifact

Markdown tables live next to prose. CSV lives next to analysis. Pretending one file can do both jobs is how READMEs become unmaintainable spreadsheets.

README patterns that actually work

Small reference (good Markdown):

| Env | Purpose |
|-----|---------|
| `DATABASE_URL` | Primary DB |
| `REDIS_URL` | Cache |

Large matrix (good CSV):

Full rate-limit matrix: [limits.csv](./limits.csv)

Preview:

| Tier | RPM |
|------|-----|
| Free | 60 |
| Pro | 600 |

Give humans a scannable preview; give analysts the file. The preview can drift if you never regenerate it — ideally both come from one source of truth in CI.

Conversion pitfalls that break trust

CSV: name,note
     Ada,"Hello, world"

Markdown needs pipes and careful handling of | inside cells. Conversely, Markdown:

| name | note |
|------|------|
| Ada | Hello \| world |

may not round-trip cleanly into every CSV dialect. Multi-line cells, embedded quotes, and locale-specific decimal commas make “just convert it” a surprise every time.

Use a Markdown table tool to shape small grids for docs. For recurring large datasets, generate CSV in CI from YAML or JSON schema instead of hand-editing either format. Hand-maintained dual copies diverge within one sprint.

GitHub and Notion specifics

GitHub Flavored Markdown supports tables; leading and trailing pipes are optional, but consistent style helps reviews. Very wide tables horizontally scroll — fine for five columns, hostile for twenty. On phones, a twenty-column README table is effectively unusable even if it “renders.”

Notion imports CSV well; Markdown tables are often better authored natively in Notion and exported only when needed. If your docs site supports HTML tables with sticky headers, that can beat both formats for huge comparison matrices.

Alignment and wrapping myths

The :---: alignment markers affect presentation, not data types. They will not make a forty-column comparison readable on a phone. If readers need to compare many fields, ship CSV or an HTML docs page. Do not spend an afternoon padding spaces so columns look aligned in a monospace editor — rendered Markdown ignores that theater.

Diffs and review culture

Wide Markdown tables make pull requests unreadable: one cell change reformats an entire row and buries the signal. CSV diffs are still noisy, but scripts can regenerate them from structured sources. Prefer editing the source (JSON, YAML, spreadsheet export) and regenerating the artifact readers consume.

Editorial rule of thumb

1. ≤ 6 columns, ≤ ~15 rows, explanatory → Markdown table inline.
2. Machine-sortable, wide, or frequently updated → CSV (or JSON) as an artifact plus a short Markdown summary.
3. Nested structure → JSON or YAML, not either grid format.

Also ask who the reader is. Support engineers scanning a README want Markdown. Analysts building reports want CSV. API consumers often want JSON. Matching the medium to the job beats arguing about which grid is “more correct.”

Docs fail when the medium fights the task. Markdown tables are for reading beside prose. CSV is for grids people open in spreadsheet tools. Convert when useful — but choose the home format on purpose, and never assume a README can replace a spreadsheet merely because both have rows and commas.