CSV to Markdown Table

How it works

The first line becomes the header row, the alignment row is written directly underneath it, and every remaining line becomes data. With the delimiter left on automatic, semicolon, comma, tab and pipe are each counted outside quoted fields, and the candidate that yields the same number of columns on every line wins; that consistency test is what stops a comma inside an address from being read as a separator. All three line endings are read as well: the CR+LF of Windows, the LF of macOS and Linux, and the lone CR of much older programs, which many tools mistake for a single long line. Pipe characters inside the cells are escaped with a backslash, because an unescaped pipe would end the cell early and push the rest of the row one column to the left. A line break inside a quoted field is turned into a <br> tag, since a Markdown table cell has to fit on a single line. Finally every cell is padded with spaces to the width of its column, so the table is legible in the raw file as well as after rendering — which matters when the .md file is reviewed as a diff. The result appears as you type, and you can copy it or download it as a .md file.

This tool is also known as csv to markdown, csv to markdown table, markdown table generator, readme table generator, make a markdown table.

What is Markdown?

Markdown is a lightweight way of writing formatted text with punctuation instead of tags: a hash at the start of a line makes a heading, asterisks around a word make it bold, a leading dash makes a list item. The source stays readable before anything renders it, which is why it became the default for repository documentation, static sites and note-taking apps. Files carry the .md extension, and because they are plain text they diff and merge cleanly in version control.

What is a Markdown table?

A Markdown table is a run of lines whose cells are separated by pipe characters, with a row of dashes immediately under the header. That second row is mandatory: it marks the block as a table, and through the position of its colons it states how the columns are aligned. A cell cannot contain a nested table, a list or a real line break — that limit is the price of a format meant to stay readable as plain text.

What is the alignment row?

The alignment row is the line of dashes sitting under the header, written once per column. The colons decide the alignment: to the left of the dashes the column is left aligned, to the right it is right aligned, on both sides it is centred, and with no colon at all the renderer's own default applies. It has to contain exactly as many cells as the header row; one cell too few and the block is not recognised as a table at all.

What is the difference between CSV and a Markdown table?

CSV is written for machines: beyond the delimiter there is no decoration, and column width and alignment are not concepts it has. A Markdown table is written for people — it carries alignment, and it looks like a table even in the raw source. The trade cuts both ways: you cannot import a Markdown table into a database, and pasting raw CSV into a README renders as one long line of text. This tool takes data that is already correct and makes it publishable; the return journey means turning the table back into data.

Which alignment should you use?

In Markdown, alignment belongs to the column rather than to the cell, and it is expressed by the colons in the dashed row under the header. This tool applies one alignment to the whole table; to vary it column by column, move the colons in the second line of the output by hand — nothing else has to change.

In practice a right alignment earns its keep in tables of amounts, counts and dates, because the digits then line up under each other and a wrong order of magnitude is visible at a glance. Text columns read better left aligned, which is why that is the default.

• Left — names, descriptions, status columns
• Centre — short labels, marks, single-letter codes
• Right — amounts, counts, percentages, dates

Where a Markdown table renders

GitHub and GitLab render these tables in README files, issues, pull request descriptions and wikis, and so do most static site generators, documentation tools and note-taking apps. Tables are not part of the original Markdown specification, though: they come from the GitHub Flavored Markdown extension, so a strict, minimal renderer may print your table as literal text instead.

You can keep editing after pasting. Adding a row means writing one more line with the same number of pipes. The space padding will drift out of line as you edit and the table still renders correctly, because that padding exists only for whoever reads the raw file.

What your data has to look like

A header line is required. If your export has none, add one at the top, otherwise your first record is promoted into the header and vanishes from the body of the table.

Rows with different numbers of cells are handled by taking the widest row as the column count and leaving the missing cells empty, so nothing shifts sideways. An empty cell is perfectly legal in a Markdown table and renders as a blank.

Frequently asked questions

Does the first line have to be a header?

Yes. A Markdown table is defined as a header line followed by the dashed alignment line, so there is no valid table without one. If your data has no header, add a line at the top yourself before converting.

What happens to a pipe character inside a cell?

It is escaped with a backslash and shows up as an ordinary character. Left alone, that pipe would close the cell early and shift every value after it one column to the left.

Are multi-line cells supported?

A line break inside a quoted field is converted to a <br> tag, because a table cell in Markdown has to sit on one line. Most renderers display that tag as a line break within the cell.

Can I align each column differently?

The tool applies a single alignment to the whole table. For per-column control, edit the colons in the second line of the output: a colon left of the dashes aligns left, right of them aligns right, and one on each side centres the column.

Is my data sent anywhere?

No. Parsing and table building happen inside your browser, so what you paste never reaches a server and the tool keeps working with the network switched off.