Skip to content

MD055 - Keep table formatting consistent

Aliases: table-pipe-style

What this rule does

Ensures all rows in your tables use the same style for leading and trailing pipe characters (|).

Why this matters

  • Visual consistency: Mixed pipe styles make tables look messy and unprofessional
  • Easier editing: Consistent formatting makes it easier to add or modify table rows
  • Better alignment: Uniform pipe placement helps maintain column alignment
  • Parser compatibility: Some Markdown parsers require specific pipe styles

Examples

✅ Correct (with leading and trailing pipes)

| Name     | Role      | Department |
| -------- | --------- | ---------- |
| Alice    | Manager   | Sales      |
| Bob      | Developer | IT         |

✅ Correct (without leading and trailing pipes)

Name     | Role      | Department
-------- | --------- | ----------
Alice    | Manager   | Sales
Bob      | Developer | IT

❌ Incorrect (mixed styles)

| Name     | Role      | Department |
| -------- | --------- | ---------- |
Alice    | Manager   | Sales
| Bob      | Developer | IT         |

🔧 Fixed

| Name     | Role      | Department |
| -------- | --------- | ---------- |
| Alice    | Manager   | Sales      |
| Bob      | Developer | IT         |

Configuration

[MD055]
style = "consistent"  # Options: see below

Style options

  • consistent (default): Use the most prevalent style in the table (in case of a tie, leading-and-trailing is preferred as it's most widely used)
  • leading-and-trailing: Require pipes at start and end: | cell |
  • leading-only: Require pipes only at start: | cell
  • trailing-only: Require pipes only at end: cell |
  • no-leading-or-trailing: No pipes at start or end: cell

Automatic fixes

This rule can automatically fix issues by:

  • Adding missing leading pipes when required
  • Adding missing trailing pipes when required
  • Removing extra pipes when not allowed
  • Making all rows match the configured style

Only rows the Markdown parser reads as a table are checked or rewritten. Rows with a delimiter row of a different cell count or invalid syntax, indented code, and raw HTML are skipped. MD056 reports a delimiter row whose cell count differs from the header.

A pipe is more than decoration, so a row is only reported when it can be rewritten without changing what it says. A row is left as written, and not reported, when removing its pipe would:

  • turn a one-column row into plain text, since a one-column table needs its pipes (the no_leading_or_trailing and trailing_only styles therefore leave one-column tables alone);
  • drop an empty first or last cell, whose only trace is its pipe;
  • leave a pipe that follows a backslash, which is cell text, or a cell ending in a backslash at the end of the line;
  • expose the start of a cell that reads as another block, such as #, -, 1., > or a fence.

Only spaces and tabs around a cell are padding. Any other whitespace character, such as a no-break space, is part of the cell and is kept.

Markdown with Gherkin

Under the mdg flavor, MD055 always uses leading_and_trailing. Gherkin recognizes a Data Table or Examples row only when an indent is followed directly by a pipe, so no_leading_or_trailing, leading_only and trailing_only would not express the required form: no_leading_or_trailing and trailing_only remove the leading pipe, while leading_only omits the trailing pipe. None of the three is adopted: the rule enforces leading_and_trailing anyway and prints one [config warning] line on stderr when the rule reaches relevant content. consistent resolves to the same form rather than by prevalence, and is never reported.

A restyled row keeps the indentation it was written with, because that indent is half of what makes it a Gherkin row. MD060 owns the indent's width.

See Markdown with Gherkin Flavor for the full flavor specification.

Learn more