CSV is the export format for almost everything — spreadsheets, database dumps, analytics dashboards. But when you’re writing a README, filing a GitHub issue, or drafting documentation, Markdown tables are what you actually want. Converting CSV to a Markdown table by hand is tedious and error-prone. This guide covers the Markdown table format, how to handle CSV edge cases, and how to convert instantly online.

Convert CSV to Markdown table →

Markdown Table Format

A Markdown table has three parts:

| Column A | Column B | Column C |
|----------|----------|----------|
| value 1  | value 2  | value 3  |
| value 4  | value 5  | value 6  |

Rules:

  • The first row is the header.
  • The second row (the separator row) uses dashes (---) and optional colons for alignment.
  • Every row must have the same number of pipe-separated cells.

Column Alignment

The separator row controls column alignment:

| Left     | Center   | Right    |
|:---------|:--------:|----------:|
| text     | text     | text     |
SyntaxAlignment
---Left (default)
:---Left (explicit)
:---:Center
---:Right

Use right alignment for numeric columns — it makes tables much easier to scan.

CSV → Markdown Table: Examples

Basic Conversion

Input CSV:

name,role,team
Alice,Engineer,Platform
Bob,Designer,Product
Charlie,Manager,Growth

Output Markdown:

| name    | role     | team     |
|---------|----------|----------|
| Alice   | Engineer | Platform |
| Bob     | Designer | Product  |
| Charlie | Manager  | Growth   |

Rendered:

nameroleteam
AliceEngineerPlatform
BobDesignerProduct
CharlieManagerGrowth

Quoted Fields with Commas

CSV handles commas inside values using double quotes:

city,description
Paris,"Capital of France, fashion hub"
Tokyo,"Capital of Japan, technology center"

The converter strips the quotes and escapes any pipe characters (|) inside values so the Markdown table structure stays valid.

Numeric Columns

For a table with numeric data, right-aligning the number columns improves readability:

product,price,units
Widget,9.99,150
Gadget,24.99,42
Doohickey,4.50,380

Output with right-aligned numbers:

| product   |  price | units |
|-----------|-------:|------:|
| Widget    |   9.99 |   150 |
| Gadget    |  24.99 |    42 |
| Doohickey |   4.50 |   380 |

Empty Cells

Missing CSV values become empty Markdown cells:

id,name,email
1,Alice,[email protected]
2,Bob,
3,,[email protected]

Output:

| id | name  | email             |
|----|-------|-------------------|
| 1  | Alice | [email protected] |
| 2  | Bob   |                   |
| 3  |       | [email protected] |

Common Use Cases

GitHub READMEs

GitHub renders Markdown tables natively in READMEs, wikis, and issues. Paste your CSV into the converter, copy the Markdown, drop it into your README.

API Documentation

Documenting request parameters or response fields? Export them from a spreadsheet, convert to Markdown, paste into your docs. Much faster than hand-formatting a table.

GitHub Issues and PRs

When reporting a bug with tabular data (test results, benchmark comparisons, config values), a Markdown table is far more readable than a code block of raw CSV.

Confluence and Notion

Both platforms accept Markdown on paste. Convert your CSV, paste it in, and the table renders automatically.

Static Site Documentation

Tools like Docusaurus, MkDocs, and VitePress all render Markdown tables. Manage your tabular content in a spreadsheet, export CSV, convert, paste.

Pipe Characters in CSV Values

The pipe character (|) is a Markdown table delimiter. If your CSV values contain pipes, they must be escaped as \| in the output:

shortcut,action
Cmd|Ctrl+C,Copy
Cmd|Ctrl+V,Paste

Becomes:

| shortcut       | action |
|----------------|--------|
| Cmd\|Ctrl+C    | Copy   |
| Cmd\|Ctrl+V    | Paste  |

Good converters handle this automatically. If yours doesn’t, search-and-replace | with \| in your CSV values before converting.

Converting in Code

JavaScript

function csvToMarkdown(csv, alignRight = []) {
  const lines = csv.trim().split('\n');
  const rows = lines.map(line =>
    line.split(',').map(cell => cell.trim().replace(/^"|"$/g, '').replace(/\|/g, '\\|'))
  );

  const headers = rows[0];
  const separator = headers.map((_, i) =>
    alignRight.includes(i) ? '---:' : '---'
  );

  const toRow = cells => '| ' + cells.join(' | ') + ' |';
  return [toRow(headers), toRow(separator), ...rows.slice(1).map(toRow)].join('\n');
}

const csv = `name,score\nAlice,95\nBob,82`;
console.log(csvToMarkdown(csv, [1])); // right-align column 1

Python

import csv
import io

def csv_to_markdown(csv_text, align_right=None):
    align_right = align_right or []
    reader = csv.reader(io.StringIO(csv_text.strip()))
    rows = [[cell.replace('|', '\\|') for cell in row] for row in reader]
    
    if not rows:
        return ''
    
    headers = rows[0]
    col_widths = [max(len(row[i]) for row in rows) for i in range(len(headers))]
    
    def fmt_row(cells):
        padded = [cells[i].ljust(col_widths[i]) for i in range(len(cells))]
        return '| ' + ' | '.join(padded) + ' |'
    
    sep = []
    for i, w in enumerate(col_widths):
        sep.append(('-' * w + ':') if i in align_right else '-' * w)
    
    lines = [fmt_row(headers), '| ' + ' | '.join(sep) + ' |']
    lines += [fmt_row(row) for row in rows[1:]]
    return '\n'.join(lines)

csv_text = "name,score\nAlice,95\nBob,82"
print(csv_to_markdown(csv_text, align_right=[1]))

Command Line (Pandoc)

Pandoc can convert CSV to various formats including Markdown:

# Requires pandoc
pandoc -f csv -t markdown data.csv

Note: Pandoc’s CSV support may require a specific version. For a simpler approach:

# Using csvkit
pip install csvkit
csvformat -T data.csv | column -t -s $'\t'

Markdown Table Limitations

Markdown tables have constraints to keep in mind:

  • No merged cells: Markdown doesn’t support colspan or rowspan. For complex layouts, use HTML tables instead.
  • No multi-line cells: Each cell must be a single line. Newlines inside cells break the table structure.
  • No styling: Font weight, color, and borders are controlled by your theme, not the Markdown.
  • Size limits: Very wide tables (30+ columns) or very long tables (1000+ rows) hurt readability. Consider splitting or using a scrollable code block.

For tables where Markdown falls short, GitHub also supports inline HTML:

<table>
  <tr><th>Name</th><th>Role</th></tr>
  <tr><td>Alice</td><td>Engineer</td></tr>
</table>

Online CSV to Markdown Converter

ZeroTool’s CSV to Markdown converter runs entirely in your browser. Paste your CSV, pick column alignment, and copy the Markdown output. No file is uploaded. No account required.

Try the CSV to Markdown converter →