Markdown tables are the fastest way to put structured data into a README, a GitHub issue or a docs page — and the most annoying thing to type by hand. Every cell needs its pipes, the header needs its separator row of dashes, and one missing | silently breaks the whole grid.
The fix is to stop typing the pipes at all. You type the data; the table builds itself.
What a Markdown table actually is
Three parts, nothing more:
- A header row —
| Plan | Price | Users | - A separator row —
| --- | ---: | ---: |, which also carries the alignment - The data rows — one line per row, cells separated by pipes
The separator row is the part people delete by accident. Without the dashes, most renderers show your "table" as plain paragraphs. It is not decoration; it is what makes the block a table — and what carries the alignment. --- is left, ---: is right, :---: is centred. Numbers read best right-aligned, because their digits line up for comparison.
A worked example
A tiny price list — three columns (Plan, Price, Users), two rows — becomes:
| Plan | Price | Users | | ----- | ----: | ----: | | Basic | 499 | 1 | | Pro | 999 | 5 | Pasted into GitHub or any Markdown renderer, that is a proper table with the numeric columns right-aligned. The spaces padding the cells exist only to keep the raw code readable — renderers ignore them.
Three mistakes that break Markdown tables
- A pipe character inside a cell. A literal
|is read as a column boundary and shatters the row. Escape it as\|— or use a tool that escapes it for you automatically. - Deleting the separator row. Covered above: no dashes, no table. If your pasted table renders as plain text, the separator row is the first thing to check.
- Expecting merged cells or multi-line content. Plain Markdown tables cannot merge cells, and a line break inside a cell breaks the row. If your data needs either, a real HTML table or a spreadsheet is the honest tool.
The free tool I built
I make BulkTextKit — 15 free text tools that run 100% in your browser, nothing uploaded. The Markdown Table Generator is the one I open for this job: type your headers and rows, choose the alignment, and it generates the table live — pipes inside cells escaped automatically — with a preview so you can check it before you paste it into GitHub, Notion or your docs.
One line on Pro: BulkTextKit Pro ($19 one-time, no subscription) adds Bulk mode — build up to 50 markdown tables at once instead of doing them one by one.
What is the fiddliest table you have ever had to type by hand — and how many pipes did it eat?
