MDS025: table-format

Tables must have consistent edge pipes, equal column counts, surrounding blank lines, and prettier-style alignment.

A GFM table must satisfy four conditions:

1. Every row’s leading/trailing pipe presence matches the configured style (the markdownlint MD055 check).
2. Every non-header row, including the delimiter row, has the same logical cell count as the header (MD056).
3. The table has a blank line before and after (MD058).
4. Each bordered table has aligned column widths and consistent padding (the prettier-style alignment pass that gave the rule its name), with the configured separator-style.

Conditions 1, 3, and 4 are auto-fixed by mdsmith fix. Condition 2 (MD056) is flagged but never auto-rewritten on its own: a missing cell’s intended content is unknown. The alignment pass does pad short rows with empty cells while it normalises widths, so a fixed bordered table is structurally clean even when the original missed a cell. A borderless table is not formatted by the alignment pass — tablefmt requires edge pipes on every row. MD056 therefore keeps firing on a borderless short row after fix; add the edge pipes or fill the cell to resolve it.

# Settings

consistent infers the required edge-pipe shape from each table’s header row and holds every other row to it. The other two values require or forbid leading and trailing pipes on every row.

Separator row examples:

• spaced (the GFM-spec form):

  | --- |

• compact (dense form):

  |---|

# Config

rules:
  table-format:
    pad: 1
    separator-style: spaced
    style: consistent

Opt into the dense compact form:

rules:
  table-format:
    separator-style: compact

Disable:

rules:
  table-format: false

# Examples

# Good

# Formatted Table

| Name   | Description               |
| ------ | ------------------------- |
| foo    | A short one               |
| barbaz | A longer description here |

# Good – alignment indicators

# Aligned Table

| Left | Center | Right |
| :--- | :----: | ----: |
| aaa  | bbb    | ccc   |

# Good – single column

# Single Column

| Item   |
| ------ |
| first  |
| second |

# Good – compact (opt-in)

With separator-style: compact the same column widths apply; only the separator row collapses its padding spaces. The fixture below carries the setting in front matter so the integration tests exercise the compact path.

# Formatted Compact Table

| Name   | Description               |
|--------|---------------------------|
| foo    | A short one               |
| barbaz | A longer description here |

# Good – borderless

# Borderless table

No leading or trailing pipe on any row. The style is
consistent, so the table passes.

Key | Value
--- | -----
a | one
b | two

# Good – blockquoted

# Blockquote table

> Quoted intro.
>
> | Key | Value |
> | --- | ----- |
> | a   | one   |
>
> Quoted outro.

# Bad – misaligned

# Misaligned Table

| Name | Description |
|---|---|
| foo | A short one |
| barbaz | A longer description here |

# Bad – alignment indicators

# Misaligned Alignment

| Left | Center | Right |
|:---|:---:|---:|
| aaa | bbb | ccc |

# Bad – mixed edge pipes (MD055)

# Mixed pipes

Key | Value
--- | -----
| a | one |
b | two

# Bad – missing cell (MD056)

# Missing cell

| Key | Value |
| --- | ----- |
| a   | one   |
| b   |

# Bad – no surrounding blanks (MD058)

# No blanks

Paragraph before.
| Key | Value |
| --- | ----- |
| a   | one   |
Paragraph after.

# Edge Cases

# Meta-Information

• ID: MDS025
• Name: table-format
• Status: ready
• Default: enabled, pad: 1, separator-style: spaced, style: consistent
• Fixable: yes (MD055 edges, MD058 blanks, alignment; MD056 column count is flagged only)
• Implementation: source
• Category: table
• markdownlint:
  • MD055 (table-pipe-style)
  • MD056 (table-column-count) (partial)
  • MD058 (blanks-around-tables)
• rumdl:
  • MD055 (table-pipe-style)
  • MD056 (table-column-count) (partial)
  • MD058 (table-spacing)
• obsidian-linter: empty-line-around-tables (partial)