How to Convert a Spreadsheet or CSV into a Markdown Table

Quick answer

A spreadsheet doesn't write Markdown, so converting one always goes through CSV first. For a small table, export to CSV and type it out by hand: pipes between columns, a hyphen divider row under the header. For anything bigger than a handful of rows, run the CSV through Pandoc instead. Both paths land in the same place — a plain-text table that renders on GitHub, in most static site generators, and in any Markdown-aware editor.

Step-by-step

1. Export your spreadsheet to CSV

If you're starting in Numbers, choose File > Export To > CSV — cell contents get written out as comma-separated values, and if the document has multiple sheets you can choose one file per table or combine them (Apple Support). Excel and Google Sheets both have the same "Save As / Export > CSV" option. None of these apps write Markdown directly, so CSV is always the intermediate step — there's no shortcut around it.

2. Know the syntax you're converting to

A Markdown table is three things: pipes to separate columns, a header row, and a divider row of hyphens under the header with at least three hyphens per column. GitHub's docs put it plainly — you need a blank line before the table or it won't render at all. The pipes at the far left and right edges are optional, and cells don't need to line up visually in the raw file; only the pipe/hyphen structure matters.

| Name  | Role      | Location |
| ----- | --------- | -------- |
| Sam   | Engineer  | Remote   |
| Priya | Designer  | Austin   |

Add colons to the divider row to set alignment: :--- for left, :---: for center, ---: for right. If a cell needs to contain a literal pipe character, escape it with a backslash (\|).

One thing worth knowing before you convert a large table: pipe tables are a GitHub Flavored Markdown (GFM) extension on top of CommonMark, not part of the core spec (GFM Spec). GitHub, GitLab, and most static site generators support GFM. A strict CommonMark renderer won't — if your table shows up as raw pipes and dashes somewhere, that's usually why.

3. Convert small tables by hand

For a handful of rows, typing the pipes is faster than reaching for a tool. Open the CSV, and for each row replace the commas with | and add the header divider line underneath row one. It's mechanical work, and for three or four columns it takes less time than uploading a file anywhere.

4. Convert larger CSVs with Pandoc

Past a dozen or so rows, do it from the command line instead:

pandoc -f csv -t markdown input.csv -o output.md

-f csv tells Pandoc to read the file as CSV (RFC 4180), and -t markdown writes it back out as a pipe table (Pandoc User's Guide). This matters more than it sounds like it should: a real-world CSV export often has quoted commas inside a cell ("Smith, John") or an embedded line break, and a naive find-and-replace on commas will silently corrupt those rows. Pandoc parses the CSV properly first, so it doesn't make that mistake. The same flag works for tab-separated files with -f tsv.

Going the other direction — starting from a Word doc or Google Doc instead of a spreadsheet — is a different path; see converting Word or Google Docs to Markdown with Pandoc.

Common problems and fixes

Table renders as plain text. Almost always a missing blank line before the table, or a divider row with fewer than three hyphens in a column. Add the blank line, check the hyphen count.

A column shifts or disappears. Usually an unescaped pipe inside a cell's content — the renderer reads it as a new column boundary. Escape it with \|.

Cell content looks cut off or merged oddly. Markdown tables can't hold multi-line content, block quotes, or other block-level elements inside a cell — everything has to stay on one line. If a spreadsheet cell has a line break in it, either strip it or move that content out of the table.

The table is unreadable on a phone screen. Very wide tables (six-plus columns) don't reflow — they just get a horizontal scrollbar or clip. Consider whether the data actually needs to be a table, or whether a shorter list, or a linked file, communicates it better. If the destination is a document rather than a webpage, exporting Markdown back out to PDF or Word with Pandoc keeps the table intact in a format built for wide layouts.

Doing this with Carets

With the CSV converted, you need somewhere to paste the result that actually understands Markdown tables — not a plain text field that shows you raw pipes with no rendering. Carets is a native Markdown and plain-text editor for iPhone, iPad, and Mac, so a pasted or typed table renders live as you work on it, pipes and all.

It's also built to hold more than one converted table without turning into a mess. Files, projects, and tags let you keep a reference document's related tables together — useful if you're converting several CSV exports into one longer Markdown doc; see structuring longer Markdown docs for how that kind of document tends to be organized. And because everything stays plain text, the file you end up with is portable — it opens the same way in any Markdown-aware app or on GitHub, with no proprietary format lock-in.

Carets is free to download on the App Store for iPhone, iPad, and Mac.

Frequently Asked Questions

Can I paste a spreadsheet directly into a Markdown table without exporting a CSV first?

Yes, for a small range. Copy the cells, then manually add pipes between columns and a hyphen divider row under the header — for anything more than a handful of rows, exporting to CSV first and converting is faster and less error-prone.

Does Markdown support merged cells like a spreadsheet does?

No. GitHub Flavored Markdown tables are strictly a grid — no merged cells, no multi-line cell content, no nested tables. If your spreadsheet relies on merged headers or wrapped text, simplify the structure before converting or keep it as a linked spreadsheet instead.

Why did my converted table lose its formatting when I opened it on GitHub?

Pipe tables are a GitHub Flavored Markdown (GFM) extension, not part of the core CommonMark spec, so a strict CommonMark renderer will show the raw pipes and hyphens as plain text instead of a table. Check that wherever you're viewing the file actually supports GFM.

What's the fastest way to convert a large CSV export to a Markdown table?

Use Pandoc from the command line: pandoc -f csv -t markdown input.csv -o output.md. It handles quoted commas and embedded newlines correctly, which a manual find-and-replace on commas will get wrong on real-world data.

Conclusion

Converting a spreadsheet to a Markdown table is really just two steps: get it to CSV, then get the CSV into pipes and a header divider — by hand for something small, with Pandoc once it's not. Past that, it's a plain-text table that lives in a file you can version, search, and edit anywhere, including in Carets.