Last updated
Why Convert CSV to Markdown?
Markdown tables are the standard way to display tabular data in README files, GitHub wikis, documentation sites (like Docusaurus, MkDocs, or GitBook), and pull request descriptions. CSV is the universal export format from spreadsheets, databases, and data tools. Converting between them is a daily task for developers writing technical documentation.
A Markdown table uses pipe characters (|) to separate columns and a separator row
of dashes to distinguish the header from the data rows. Most Markdown renderers support
optional column alignment using colons in the separator row.
Markdown Table Syntax
| Name | Age | City |
| ------- | --- | ----------- |
| Alice | 30 | New York |
| Bob | 25 | Los Angeles |
| Charlie | 35 | Chicago |
<!-- Column alignment with colons: -->
| Left | Center | Right |
| :------ | :----: | -----: |
| text | text | text |CSV Edge Cases to Watch For
Simple CSV splitting on commas breaks when cell values contain commas or newlines. The RFC 4180 CSV standard specifies that such values must be wrapped in double quotes:
- Commas in values:
"New York, NY"— the whole value is quoted. - Quotes in values:
"He said ""hello"""— double-quote is escaped by doubling it. - Newlines in values:
"Line 1 Line 2"— quoted values can span multiple lines. - Different delimiters: Some CSV files use semicolons (
;) or tabs (
Converting in the Terminal
import csv, sys
def csv_to_markdown(filepath):
with open(filepath, newline='', encoding='utf-8') as f:
reader = csv.reader(f)
rows = list(reader)
if not rows:
return ''
# Header row
header = rows[0]
lines = ['| ' + ' | '.join(header) + ' |']
lines.append('| ' + ' | '.join(['---'] * len(header)) + ' |')
# Data rows
for row in rows[1:]:
# Pad short rows, escape pipe chars
cells = [c.replace('|', '\|') for c in row]
while len(cells) < len(header):
cells.append('')
lines.append('| ' + ' | '.join(cells) + ' |')
return '
'.join(lines)
print(csv_to_markdown(sys.argv[1]))Markdown Table Limitations
Standard Markdown tables don't support merged cells, multi-line cells, or complex formatting. For those cases, use HTML tables directly — most Markdown renderers pass through raw HTML. GitHub Flavored Markdown (GFM) supports basic tables but not colspan or rowspan.