scalpel@labs: ~/glossary/markdown-table-format.mdx5 sections

Markdown Tables - The Pipe Syntax and Its Limits

A Markdown table uses pipes to separate columns and a dashed line under the first row to mark the header, as defined by GitHub Flavored Markdown. It is great for READMEs and issues, but it cannot show merged cells and treats a literal pipe in a cell as a column break unless escaped.

extension: Scalpel Tablesupdated: 2026-08-14read_time: 2 min
less markdown-table-format.mdx

Why it matters

Markdown tables let you paste data into GitHub issues, pull requests, wikis, and README files without importing a separate format. They're readable in plain text, version-controlled well, and render instantly on GitHub. If your workflow lives in plain-text docs or version control, Markdown is the obvious choice.

But Markdown tables have hard limits. They are one header row and no merging. Any content that needs colspan or rich structure has to go somewhere else.

How it works

GitHub Flavored Markdown (GFM) defines pipe tables with three elements:

  • Columns separated by | (pipe)
  • A header row
  • A delimiter row under the header made of --- (dashes)
| Name    | Age | City      |
| ------- | --- | --------- |
| Alice   | 28  | New York  |
| Bob     | 34  | San Diego |

The parser reads the pipe-separated columns and treats the first row as headers (by default). Alignment can be added by using colons in the delimiter row: |:---| for left, |:-:| for centre, |---:| for right.

What does not matter

First, Markdown tables do not need perfect alignment. You can write:

|Name|Age|City|
|---|---|---|
|Alice|28|New York|

It parses exactly the same. The whitespace is for human readability.

Second, the format cannot express anything GFM doesn't define. No line breaks inside cells (the parser reads one row per line). No colspan or rowspan. No nested tables. These are not bugs; they're design limits. If your data needs them, use CSV or XLSX instead.

Third, a header row is always the first row. Some tables don't have headers. You can skip the header entirely by treating all rows as data, but the delimiter row stays, so a two-row table in Markdown will always look like it has headers.

Code example

Here's a table with a pipe inside a cell and its correct escaped form:

// Wrong - the pipe breaks the column
| Command | Description |
| ------- | ----------- |
| git \| grep | Filter git output |

// Correct - the pipe is escaped
| Command | Description |
| ------- | ----------- |
| git \| grep | Filter git output |

Scalpel Tables handles the escaping automatically, so you paste the exact Markdown and columns stay intact.

How Scalpel Tables shows it

Click the "Copy as Markdown" option in the overflow menu (three dots) on any table card. Scalpel copies the table in pipe-table syntax, with any literal pipes already escaped as \|. Paste it directly into a GitHub issue, README, or wiki.

Related:

Sources