---
name: markdown-table-format
source: https://app.decimal.ai/s/markdown-table-format@1/SKILL.md
source_sha256: 748f06a26298
---

# 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.

2. **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.

3. **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.

4. **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.

5. **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.

6. **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.