How to Convert a CSV to a Markdown Table (For GitHub, Notion and Docs)

To convert a CSV to a Markdown table, write the header row between pipes, add a line of dashes under it, then write each data row the same way. The CSV to Markdown table tool does it for you. Upload a CSV or .xlsx file, or paste it, choose Markdown or HTML, the alignment and the most rows to write, then copy the table or download it as a .md or .html file.

The file is read in your browser and not uploaded.

What a Markdown table looks like

Each row sits on one line with cells between pipes, and a second line of dashes sits under the header. GitHub, GitLab, Notion, Obsidian and most documentation tools draw it as a grid:

| Name | Plan | Seats |
| :--- | :--- | ---: |
| Ava  | Pro  |     5 |
| Ben  | Free |     1 |

Colons in the dashes line set the alignment: a colon on the right right-aligns the column, on the left left-aligns it. In automatic mode the tool right-aligns columns that hold only numbers and left-aligns the rest.

Doing it by hand

For a small table, type it. For a bigger one in Excel or Sheets, add a helper column that joins the cells, for example ="| "&A2&" | "&B2&" | "&C2&" |", then fill it down and copy the column. Add the header line and the dashes line yourself.

That breaks as soon as a cell contains a pipe or a line break, because either one splits or ends the row. The tool handles both.

Step 1: load the file

Upload the CSV or .xlsx, or paste the cells with the header row first.

Step 2: choose the format

Pick Markdown or HTML, the alignment, and the most rows to write. Very long tables are hard to read in a README. The table stops at your limit and the number left out is shown.

Step 3: check and copy

Check the table in the box and the preview below it. Copy it into a README, a doc or a chat, or download it.

How awkward cells are handled

A pipe inside a cell is written as a backslash and a pipe. A line break inside a cell becomes a br tag, because a Markdown table row must stay on one line. In the HTML format, the characters that mean something in HTML (less than, greater than, ampersand and quotes) are escaped. The Markdown is padded with spaces so the source lines up and is easy to edit; viewers ignore the extra spaces.

Other formats

For a spreadsheet use CSV to Excel. For JSON use CSV to JSON, which converts both ways, and see converting a JSON contact export to CSV. To tidy the columns before building the table, use the CSV column editor.

What this tool cannot do

• Markdown tables cannot merge cells or hold line breaks, so breaks become a br tag.
• Very wide tables are hard to read in most viewers.
• It writes the table text only; styling is up to the page it is pasted into.
• Only the first sheet of a workbook is read.

If the table holds email addresses

Before you share a table of contacts, check the addresses. Upload them on the verify page: the first 100 email checks are free with a Google sign-in, no card. Each address comes back valid, risky or invalid with a reason, and nothing is sent to anyone on the list. For larger lists, see bulk email verification and pricing.

Build your table now

Open the CSV to Markdown table tool.