What the generator does
This Markdown table generator turns an editable grid, or a block of CSV or TSV pasted straight out
of a spreadsheet, into a GitHub Flavored Markdown table. You choose the alignment of each column,
the pipes are padded so the raw text stays readable, bars inside a cell are escaped, and line breaks
become <br> because Markdown has no multi-line cell.
Everything happens in the page. Nothing is uploaded, which matters when the table you are pasting came out of an internal report.
Tables are GFM, not CommonMark
This surprises people, and it explains most of the times a table renders as a wall of pipes. The CommonMark specification has no table syntax at all. Tables arrived through GitHub Flavored Markdown and were adopted from there by nearly everything, but adoption is not the same as the core standard.
In practice that means tables work in GitHub, GitLab, Bitbucket, Obsidian, Docusaurus, MkDocs, Hugo, Jekyll, VS Code preview and Discourse, and fail in anything running a plain CommonMark parser with no extensions. If a table has to survive an unknown renderer, an HTML table is the only safe answer.
The delimiter row is the whole grammar
A Markdown table is three parts: a header row, a delimiter row and any number of body rows. The delimiter row is the one that carries meaning beyond decoration.
--- sets no alignment and lets the renderer decide, which in every renderer worth naming means
left. :--- forces left, ---: forces right and :---: centres. There is no way to align a single
cell, only a whole column, and there is no vertical alignment at all.
The header row is not optional either. Because the delimiter row must sit directly under it, a table cannot begin with data, and there is no headerless variant. If your data genuinely has no header, the honest options are a first row of empty cells or a list instead of a table.
Padding, and why the compact toggle exists
Both of these render identically:
| Name | Since |
| :----------- | ----: |
| Ada Lovelace | 1843 |
| Name | Since |
| :--- | ---: |
| Ada Lovelace | 1843 |
The padded version is far easier to read and edit in the raw file, which is the whole point in a README or a design document that people open in an editor. The compact version wins when the table is generated by a script on every build: with padding, changing one value can widen a column and rewrite every line of the table, so a one-word change shows up in review as a twenty-line diff.
Pick padded for documents that humans maintain and compact for anything a machine regenerates.
When a table is the wrong shape
A Markdown table is a grid of short strings and nothing else. If the cells contain paragraphs, code blocks, lists or images, the syntax will technically hold but the result is unreadable on a phone, where a wide table either scrolls sideways or squashes to nothing.
Three columns is comfortable, five is the practical limit for prose documentation, and beyond that a definition list or a set of subheadings usually communicates better. Long free-text notes belong under the table, not inside it.
If the data started life as a spreadsheet export, the CSV to JSON converter is the better destination when the target is code rather than a document, and JSON to CSV covers the trip back. To put the rows in a sensible order before you paste them here, sort lines does it without a spreadsheet.