The problem: your data lives in CSV, your docs want Markdown
You've got a query result, a spreadsheet export, or a config dump as CSV — and you need it in a README, a
pull-request description, a GitHub issue, or a docs page. Those all speak Markdown tables, and
hand-building one is miserable: you count columns, line up pipes, add the --- separator row, and re-do the
whole thing the moment a value changes. For anything past three rows it's not worth doing by hand.
Fastest path: paste the CSV, copy the table
Drop your CSV into the CSV to Markdown Table Converter. It auto-detects the delimiter (comma, tab, semicolon, or pipe), parses quoted fields correctly, and emits a GitHub-flavored Markdown (GFM) table you can paste straight into a README.
Given this CSV:
name,role,active
"Ada, L.",admin,true
Grace,billing,false
you get:
| name | role | active |
| ------- | ------- | ------ |
| Ada, L. | admin | true |
| Grace | billing | false |
Note the first row's comma inside quotes stayed inside one cell — that's the parsing detail most naive "split on comma" scripts get wrong.
The parts a converter handles that hand-editing botches
Markdown tables have a few rules that are easy to violate by hand:
- The header separator is mandatory. Every GFM table needs the
| --- | --- |row directly under the header. Miss it and the whole thing renders as plain text, not a table. - Pipes inside cells must be escaped. A value like
a|bbreaks the table unless it becomesa\|b. If your data contains pipes (common in log lines or regexes), a converter escapes them; a copy-paste won't. - Column alignment is encoded in the separator. Left/center/right alignment isn't a cell property — it's
set by where the colons go in the separator row:
:---(left),:--:(center),---:(right). Use right-alignment for numeric columns so they read cleanly. - Ragged rows. If some CSV rows have fewer fields than the header, a good converter pads them; a manual table silently misaligns from that row down.
Gotchas worth knowing
- Markdown tables don't do multi-line cells. A CSV value with a newline inside it can't render as a true
multi-row cell — you'll need to replace the newline with
<br>or flatten it. Decide which before pasting. - Very wide tables overflow. GitHub scrolls wide tables, but a 15-column table is unreadable in a PR. If it's that wide, consider whether a table is even the right format, or split it.
- Leading/trailing spaces get trimmed by most renderers, so don't rely on padding for meaning.
- The first CSV row is assumed to be the header. If your export has no header row, add one first, or the first data row becomes column titles.
When you want the reverse, or a different target
- Need to go the other way — a Markdown/HTML table back into data? Round-trip through CSV first.
- Have JSON instead of CSV? Convert it with JSON to CSV, then to a table.
- Turning the same data into a database seed instead of docs? Use JSON to SQL INSERT.
Summary
- A Markdown table needs a header and the
| --- |separator row — the #1 reason tables render as text. - Escape pipes, set alignment via colons in the separator, and pad ragged rows.
- Paste your CSV into the CSV to Markdown converter and it handles all of that, including quoted fields with embedded commas.
- Flatten newlines to
<br>and keep tables narrow enough to read in a PR.