On-device AI — professional-grade, fully private.

Documents

CSV to Markdown Table: How to Convert a CSV for GitHub, READMEs and Docs

Turn a CSV into a Markdown table for GitHub, a README or docs: set column alignment, keep pipes and line breaks from breaking cells, and know the size limits.

Updated November 8, 20269 min read

To turn a CSV into a Markdown table, drop the file into a CSV to Markdown converter, check the rendered preview, set the alignment of each column, and copy the result into your README, issue or docs page. The converter writes the three parts every Markdown table needs: a header row, a separator row of dashes, and one line per record. The hard part is not the shape. It is the cells: a pipe character, a line break inside a quoted field or a stray asterisk can split a row, push data into the wrong column or turn text into italics. This guide covers the steps, alignment, those problem characters and the size limits that matter before you paste.

How to convert a CSV to a Markdown table

1

Add the CSV

Open the CSV to Markdown converter and drop in a .csv, .tsv, .txt or .psv file. The delimiter, quote character and encoding are detected from the file, and the tool tells you what it chose.

2

Check the header row

Leave First row as header on when row one holds column names. Turn it off if the file starts straight with data; the table then gets generated Col 1, Col 2 labels.

3

Set alignment

Pick a default Alignment for the whole table, then change any single column from the dropdown in its preview header. Numbers usually read best right-aligned.

4

Check the preview both ways

Switch between Rendered and Markdown. The rendered view shows whether a cell with an asterisk or a line break behaves; the raw view shows what you will actually paste.

5

Copy or download

Press Convert to Markdown, then Copy Markdown for a README or pull request, or Download .md with the filename you typed under Download as.

What a Markdown table is made of

A Markdown table in the GitHub-Flavored dialect is plain text. The first line is the header, cells separated by pipes. The second line is the separator: dashes under each column, and its presence is what makes the block a table at all. Every line after that is one record. GitHub, GitLab, Obsidian, VS Code and most static site generators read this same format, so one converted table works in all of them.

The format has hard limits worth knowing before you start. There is no way to merge cells across rows or columns, every row must sit on a single line, and the header is always rendered bold. If a CSV row has fewer cells than the header, the converter pads it with empty cells; if it has more, the table is widened to the widest row, so nothing is silently cut off.

Column alignment in a Markdown table

Alignment lives only in the separator row, as colons placed beside the dashes. The converter writes them for you, and it can write a different one for each column:

AlignmentSeparator writtenBest for
Left:---Names, labels, free text
Center:---:Short status columns, yes/no, single marks
Right---:Prices, counts, percentages
None---Leave it to the renderer (left almost everywhere)

A table that mixes a product name with a price and a stock count is the common case: set the table default to Left, then switch the two number columns to Right in their preview headers. Right-aligned figures line up on their last digit, which is what lets a reader compare a column of numbers by eye. Note that some apps ignore the colons; Notion, for example, turns a pasted Markdown table into its own table and drops the alignment.

Per-column alignment, safe escaping for pipes and line breaks, padded or compact output, copy or .md download. Free: one CSV up to 25 MB, no row limit, every formatting option included. Pro: up to 50 files at once as a ZIP or one merged document. It all runs on your device, not our servers.

Convert CSV to Markdown

Pipes, line breaks and characters that break a table

Spreadsheet text does not know it is about to become Markdown. These are the characters that cause trouble, and what the converter does with each:

In a cellWhat goes wrong unescapedWhat the converter does
A pipe |It ends the cell early; the row gains a column and data shiftsAlways escaped as \|
A backslashIt can swallow the character after itAlways doubled, so a Windows path survives
A line break in a quoted fieldThe row ends mid-cell and the rest of the table falls apartBecomes <br> by default, or a literal \n, or a space
Asterisks, underscores, backticksText turns bold, italic or into codeEscaped only when Escape Markdown characters is on
Brackets, angle brackets, tildesCan become links, HTML or strikethroughEscaped with the same switch
Hyphens, full stops, plus signsNothing, inside a table cellLeft alone, so dates and prices stay readable

The setting for line breaks is Line breaks in a cell. Keep <br> for GitHub and GitLab, where it renders as a real break and a postal address stays one readable cell. Choose literal \n when the table goes somewhere that strips HTML and you still want to see that a break was there. Choose Space when the breaks were an accident of the export, such as wrapped text in a spreadsheet column.

Leave Escape Markdown characters off unless the preview shows a problem. Most tables contain none of these characters, and when the switch is on every one of them gets a visible backslash in the raw file. A cell holding a value such as _draft_ or a word wrapped in asterisks is the case where you do want it: without escaping, it renders in italics and the marks disappear.

Getting the CSV read correctly first

Many broken tables are broken before any Markdown is written, because the CSV was split on the wrong character. The converter tests comma, semicolon, tab and pipe on a sample and keeps the one that gives the most consistent row widths, and it says so if the reading looks uncertain. European exports often use semicolons; if the preview shows everything in one column, set Delimiter by hand.

  • Encoding: if accented names show as garbage, the file is probably Windows-1252 rather than UTF-8. Set it by hand; a file that carries a byte-order mark always wins, and the invisible mark that Excel's CSV UTF-8 export adds is removed so it does not stick to your first heading.
  • Skip leading rows: report exports often have a title and a date above the real header. Skip those so row one becomes the header.
  • Remove empty rows and Remove empty columns: spreadsheet exports collect blank rows at the bottom and unused columns at the side. Each would become empty cells in your table.
  • Limit rows: a README needs the first 20 rows of a large export, not all of them. 0 keeps every row.

If the table needs fewer columns than the CSV has, drop them first with Add or Remove CSV Columns, and see removing columns from a CSV for the details. A table with four focused columns reads far better than one with twelve.

Size limits: the converter and where you paste

On the free tier the converter takes one file up to 25 MB, with no limit on rows. The site measures a 25 MB export of about 225,000 rows converting in around a second on a desktop. The preview shows only the first rows and columns so the page stays quick, but the download and the copied text contain all of them. Pro converts up to 50 files at once, either as one ZIP or merged into a single Markdown document with each table under a heading taken from its file name.

The tighter limit is usually the destination, not the converter:

DestinationPractical limitWhat to do
GitHub issue, pull request or commentThe body is capped at 65,536 charactersUse Limit rows, or commit the table as a .md file instead
README or docs file in a repositoryNo small cap, but a very long table is hard to readShow a sample and link the full CSV
Any page read on a phoneWide tables scroll sidewaysKeep it to about 4 to 6 columns
Raw text in an editorPadding makes every line as wide as the widest valueUse compact output for long text cells

Remember that Markdown is bigger than the CSV it came from: every cell gains pipes and spaces, and padding adds more. A full export rarely belongs in a document. Twenty well-chosen rows with a link to the source file is what most readers want.

Other options worth knowing

  • Number the rows adds a counting column, handy when reviewers need to say "row 14 is wrong" in a comment.
  • Bold first data row and Bold first column apply to the body only, since the header is already bold when rendered.
  • Quote character can be set to double quote, apostrophe or none; a quote only opens a field at its start, so the apostrophe in O'Brien stays text.

When a Markdown table is the wrong choice

Markdown tables are for small, readable data inside text. If someone needs to sort, filter or calculate, give them the data as a spreadsheet with CSV to Excel. If code will read it, CSV to JSON is the better format. If you only need to look through a big file before choosing rows, open it in the CSV Viewer first.

If your table starts in a Word document rather than a CSV, the job is different: headings, lists and formatting come along with it. That is covered in converting Word to Markdown, using the Word to Markdown tool.

Frequently asked questions

How do I convert a CSV to a Markdown table?

Drop the CSV into the CSV to Markdown converter, keep First row as header on if row one holds column names, set the alignment, then press Convert to Markdown and copy the result or download it as a .md file. The header row, separator row and escaping are written for you.

How do I right-align a column in a Markdown table?

Put a colon at the right end of that column's separator, written ---:. In the converter you set it from the dropdown in the column's preview header, so the number columns can be right-aligned while text stays on the left.

How do I put a pipe character inside a Markdown table cell?

Escape it as \| so it is not read as the end of the cell. The converter does this to every pipe automatically, including pipes inside text that looks like code.

Can a Markdown table cell contain a line break?

Not directly: each row must be one line. On GitHub and GitLab a <br> inside the cell renders as a line break, which is the converter's default for multi-line CSV fields. You can also choose a literal \n or a single space instead.

Why is my whole CSV showing up as one column?

The file uses a different delimiter than the one being applied, most often a semicolon in exports from European versions of Excel. Set the Delimiter by hand to Semicolon, Tab or Pipe and the columns separate.

Is there a size limit for converting CSV to Markdown?

The free tier converts one file up to 25 MB with no row limit and every formatting option. Pro handles up to 50 files at once. The more common limit is the destination: GitHub caps an issue or pull request body at 65,536 characters, so use Limit rows for tables pasted there.

Keep reading

More in Documents →