Markdown table format

Contract

Enforces the GitHub-Flavored-Markdown table format, normalized the way a Markdown formatter emits it: outer pipes on every row, a colon-aligned delimiter row, space-padded aligned source, and escaped pipes. Apply whenever the task is to lay data out as a Markdown table; not to compute or interpret the data.

Rules

1. Three parts, blank line before. A table is a header row, then a delimiter row, then one data row

per line. Leave a blank line between the table and any prose above and below it.

1. Outer pipes on every row. Every row — header, delimiter, and each data row — begins with | and

ends with |. Never the pipe-between-cells-only form (a | b) with no outer pipes.

1. Delimiter row = hyphens + alignment colons. The second row holds only hyphens (at least three per

column) and optional colons that set alignment:

• :--- → left, :---: → center, ---: → right, plain --- → default (left).
• Right-align numeric / amount columns (---:); leave text columns default-aligned.

1. Pad the source so columns line up. Pad each cell with spaces so the | separators align vertically

down the whole table, and make each delimiter's dashes span that column's width. This changes nothing about how the table renders — it makes the raw source readable, which is the whole point.

1. Escape a literal pipe as \|. A | that is part of a cell's text is written \|, so it is not

read as a column separator.

1. One row per line, equal cells. Each row is a single line; no wrapping. Every row has the same

number of cells as the header.

Worked examples

The base's unpolished default is on the left; the conforming table on the right.

Ragged, no outer pipes, no alignment — a short drinks menu with a price column:

BEFORE  Drink | Size | Price
        --- | --- | ---
        Espresso | Small | 3
        Flat White | Regular | 4.5

AFTER   | Drink      | Size    | Price |
        | :--------- | :------ | ----: |
        | Espresso   | Small   |     3 |
        | Flat White | Regular |   4.5 |

The price column is right-aligned (----:); text columns stay default; the | separators line up in the source; every row has outer pipes.

A cell whose text contains a literal pipe — it must be escaped:

BEFORE  | Key       | Combo     |
        | Split     | Ctrl|K    |

AFTER   | Key   | Combo   |
        | :---- | :------ |
        | Split | Ctrl\|K |

Edge cases & exceptions

• A very wide column need not be padded to its full content width if that makes the source unwieldy;

keep the pipes aligned at a sensible width and stay consistent down the column.

• An empty cell is still a padded cell between two pipes (| |), never a dropped column — every

row keeps the same cell count.

• Multi-line cell content is not allowed in GFM: join it with <br> or a space; a row is one line.
• A leading #, -, or * in a cell is fine inside a table cell and is not escaped; only | is.
• Center alignment (:---:) is reserved for genuinely centered columns (short status flags); do not

center numbers — right-align them.

Do / Don't

• Do put a | at the start and end of every row. Don't use the outer-pipe-less a | b form.
• Do right-align numeric columns with ---:. Don't leave a numbers column default-aligned.
• Do pad cells so the source pipes line up. Don't leave the raw table ragged.
• Do escape a literal | in cell text as \|. Don't leave it to break the column split.
• Do leave a blank line before the table. Don't butt it against the paragraph above.
• Do keep every row's cell count equal. Don't drop a trailing empty cell.

Common mistakes

• Omitting the outer leading/trailing pipes.
• A ragged, unpadded source where the | separators do not line up.
• No alignment colons at all, so a numbers column stays left-aligned.
• An unescaped | inside cell text, silently splitting the row into an extra column.
• The table jammed directly against the paragraph above it, with no blank line.
• Rows with differing cell counts.

Quick checklist

• ] Every row (header, delimiter, data) has outer | pipes.
• ] Delimiter row is hyphens + colons; numeric columns right-aligned (---:).
• ] Cells padded so the source | separators line up.
• ] Literal pipes in cells escaped as \|.
• ] Blank line before (and after) the table.
• ] Every row has the same number of cells.