CSV to Markdown Table Converter

What a Markdown table actually is

A Markdown table is three ingredients: a header row, a delimiter row of dashes that tells the parser “the line above was headers”, and as many body rows as you like. Every cell is fenced by pipes.

| Region | Units | Revenue |
| :--- | ---: | ---: |
| North | 1284 | $41,208 |
| South | 942  | $29,733 |

Tables are not part of original Markdown — they arrived with GitHub Flavored Markdown, which is now what almost everything speaks: GitHub and GitLab, Obsidian, Bear, Notion’s import, Discourse, Docusaurus, MkDocs, and Bulguritto. The converter above emits GFM, so the output pastes into any of them unchanged.

The delimiter row is also where alignment lives. :--- is left, ---: is right, and :---: is centred. That is the whole syntax — there is no column width, no cell merging, and no nested tables. If your spreadsheet has merged cells, flatten them before you convert.

Why CSV is harder than it looks

“Split on commas” works right up until a field contains a comma. The CSV convention, formalised as RFC 4180, is that such a field gets wrapped in double quotes, and a literal quote inside it is written twice. So this line is three cells, not four:

Smith,"Boston, MA","She said ""hello"""

A quoted field may also contain line breaks, which means you cannot even split a CSV file on newlines before parsing it. The converter above walks the file character by character to get this right, then folds any newline inside a cell into <br> — the only way to put a line break inside a Markdown table cell.

Two more things get escaped on the way out. A literal pipe would end the cell early, so it becomes \|. A literal backslash is doubled so it survives the round trip. Everything else passes through untouched, including Markdown you may have had in the spreadsheet — bold and links in a cell keep working.

Commas, semicolons and tabs

Excel in a European locale exports semicolons, because the comma is already the decimal separator. Copying a range straight out of Excel, Numbers or Google Sheets and pasting it puts tabs on your clipboard rather than commas. Both work here: the detector tries all four common delimiters and keeps whichever yields a consistent column count across the rows. If it lands on the wrong one you get a single fat column, which the tool tells you about — set the delimiter by hand and it is fixed.

Getting the CSV in the first place

• Excel: File → Save As → CSV UTF-8 (Comma delimited). Pick the UTF-8 variant, or accented characters and currency symbols come out mangled.
• Google Sheets: File → Download → Comma-separated values. Or just select the range and copy — the clipboard gives you TSV, which this tool reads directly.
• Numbers: File → Export To → CSV.
• A database: most clients have a “copy as CSV” on a result set; psql has \copy … to … csv header.

If your source is an .xlsx file with several sheets, the Excel to Markdown converter reads the workbook directly and gives you one table per sheet. For an API response, use JSON to Markdown instead.

Where the table ends up

The usual destinations are a README, a pull-request description, a wiki page, or a note. The first three are why the format exists. The last one is the interesting case: if your notes app stores Markdown natively, a converted table is just content — you can paste it in, edit the cells later, and it stays a table in a file you can still read with anything else in ten years.

That is what Bulguritto does. Every note is a plain Markdown document on disk, synced between iPhone, iPad and Mac, with tables you can edit as tables rather than as raw pipes. No import step, no proprietary database, and no need to come back to a converter next time.