MD060 - Table Format¶

Aliases: table-format

Enabled by default: No (opt-in)

Fixable: Yes

Rationale¶

Tables in Markdown are significantly easier to read and maintain when their columns are properly aligned in source form. While Markdown tables render the same regardless of spacing, aligned tables in source code:

• Improve readability during code review
• Make editing cells more intuitive
• Provide better developer experience
• Ensure consistency across documents

This rule enforces consistent column alignment and padding in Markdown tables, matching the behavior of popular formatters like Prettier.

Configuration¶

[MD060]
enabled = false              # Default: opt-in for conservative adoption
style = "aligned"            # Options: "aligned", "aligned-no-space", "compact", "tight", "any"
max-width = 0                # Default: inherit from MD013's line-length
column-align = "auto"        # Options: "auto", "left", "center", "right"
column-align-header = "auto" # Override alignment for header row only
column-align-body = "auto"   # Override alignment for body rows only
loose-last-column = false    # Cap last column at header width when true

Options¶

enabled¶

Type: boolean Default: false

Whether to enable MD060 table formatting. This rule is disabled by default to allow gradual adoption, as it can make significant changes to existing tables.

style¶

Type: string Default: "any" Values: "aligned", "aligned-no-space", "compact", "tight", "any"

Controls the table formatting style:

• aligned: Columns are padded with spaces for visual alignment (recommended for readability)
• aligned-no-space: Like aligned, but delimiter row has no spaces around dashes (see below)
• compact: Minimal spacing with single spaces between pipes and content
• tight: No spacing, pipes directly adjacent to content
• any: Preserve existing formatting style (no enforcement)

max-width¶

Type: number Default: 0 (inherit from MD013)

Maximum table width before auto-switching to compact mode.

• 0 (default): Smart inheritance from MD013's settings (see below)
• Non-zero: Explicit max width threshold, independent of MD013

When a table's aligned width would exceed this limit, MD060 automatically uses compact formatting instead to prevent excessively long lines. This intelligent auto-compacting matches Prettier's table formatting behavior.

Smart Inheritance Behavior (when max-width = 0):

When max-width is not explicitly set, MD060 intelligently determines whether to apply width limits:

This means if you don't care about table line length (by disabling MD013 or setting tables = false), MD060 won't force tables to compact. Your aligned tables will stay aligned regardless of width.

Why this matters: Wide tables with many columns or long content can produce extremely long lines when aligned. Auto-compacting ensures tables don't violate line length limits while still maintaining alignment where practical. However, if you've explicitly opted out of line length checks for tables, MD060 respects that choice.

column-align¶

Type: string Default: "auto" Values: "auto", "left", "center", "right"

Controls how cell text is aligned within the padded column width:

• auto (default): Respects alignment indicators from the delimiter row (:--- for left, :---: for center, ---: for right)
• left: Forces all columns to left-align text (content on left, padding on right)
• center: Forces all columns to center text (padding split on both sides)
• right: Forces all columns to right-align text (padding on left, content on right)

Note: This option only applies when style = "aligned" or style = "aligned-no-space". It has no effect on compact or tight styles (which have minimal or no padding).

Example:

[MD060]
enabled = true
style = "aligned"
column-align = "right"  # Right-align all cell content

column-align-header¶

Type: string (optional) Default: Not set (falls back to column-align) Values: "auto", "left", "center", "right"

Overrides column-align specifically for the header row. When set, the header row uses this alignment while body rows use column-align (unless overridden by column-align-body).

Example:

[MD060]
enabled = true
style = "aligned"
column-align-header = "center"  # Center header text
column-align-body = "left"      # Left-align body text

column-align-body¶

Type: string (optional) Default: Not set (falls back to column-align) Values: "auto", "left", "center", "right"

Overrides column-align specifically for body rows (non-header, non-delimiter). When set, body rows use this alignment while the header row uses column-align (unless overridden by column-align-header).

Example:

[MD060]
enabled = true
style = "aligned"
column-align = "left"           # Default for both
column-align-body = "right"     # Override body to right-align

loose-last-column¶

Type: boolean Default: false

Controls whether the last column width is capped at the header text width. This is useful for tables where the last column contains descriptions or other variable-length content.

• false (default): All columns are padded to the widest cell across all rows. Every row has equal length.
• true: The last column width is capped at the header text width. Body cells shorter than the header are padded to the header width. Body cells longer than the header extend beyond without extra padding.

[MD060]
loose-last-column = true

| Name   | Status   | Description |
| ------ | -------- | ----------- |
| Foo    | Enabled  | Short       |
| Bar    | Disabled | A much longer description that would waste space if padded |

Notice that "Short" is padded to match the "Description" header width, while the longer body cell extends beyond the header.

Examples¶

❌ Incorrect (unaligned)¶

| Name | Age | City |
|---|---|---|
| Alice | 30 | Seattle |
| Bob | 25 | Portland |

✅ Correct (aligned)¶

| Name  | Age | City     |
| ----- | --- | -------- |
| Alice | 30  | Seattle  |
| Bob   | 25  | Portland |

Compact Style¶

When style = "compact":

| Name | Age | City |
| --- | --- | --- |
| Alice | 30 | Seattle |
| Bob | 25 | Portland |

Tight Style¶

When style = "tight":

|Name|Age|City|
|---|---|---|
|Alice|30|Seattle|
|Bob|25|Portland|

Column Alignment Examples¶

When column-align = "center":

| Name  | Age |   City   |
| ----- | --- | -------- |
| Alice | 30  | Seattle  |
|  Bob  | 25  | Portland |

When column-align = "right":

|  Name | Age |     City |
| ----- | --- | -------- |
| Alice |  30 |  Seattle |
|   Bob |  25 | Portland |

This is useful for consistently formatting tables with numeric data or when you want a specific visual style across all columns.

Aligned No-Space Style¶

When style = "aligned-no-space":

| Name  | Age | City     |
|-------|-----|----------|
| Alice | 30  | Seattle  |
| Bob   | 25  | Portland |

This style is identical to aligned except the delimiter row has no spaces around the dashes. Compare:

• aligned: | ----- | --- | -------- |
• aligned-no-space: |-------|-----|----------|

Both styles produce aligned columns with equal-length rows. The only difference is the delimiter row formatting. This style is popular in hand-written tables and used by projects like GitLab and Obsidian.

Auto-Compact Threshold¶

Example: Inheriting from MD013¶

[MD013]
line-length = 100

[MD060]
enabled = true
style = "aligned"
max-width = 0  # Tables exceeding 100 chars will auto-compact

Behavior:

• Tables ≤ 100 chars wide: Aligned with full padding
• Tables > 100 chars wide: Automatically compact to stay under limit

Example: Explicit Threshold¶

[MD060]
enabled = true
style = "aligned"
max-width = 120  # Independent of MD013, uses 120 char threshold

Unicode Support¶

MD060 properly handles various Unicode characters:

✅ Supported¶

CJK Characters (Chinese, Japanese, Korean):

| Name | City |
| ---- | ---- |
| 中文 | 東京 |

Basic Emoji:

| Status | Name |
| ------ | ---- |
| ✅     | Pass |
| ❌     | Fail |

The rule correctly measures CJK characters as double-width and aligns columns accordingly.

⚠️ Automatically Skipped¶

Tables containing complex Unicode sequences are automatically skipped to prevent alignment corruption:

• Zero-Width Joiner (ZWJ) emoji: 👨‍👩‍👧‍👦, 👩‍💻
• Zero-Width Space (ZWS): Invisible word break opportunities
• Zero-Width Non-Joiner (ZWNJ): Ligature prevention marks
• Word Joiner (WJ): Non-breaking invisible characters

These characters have inconsistent or zero display widths across terminals and fonts, making accurate alignment impossible. The rule preserves these tables as-is rather than risk corrupting them.

Example (automatically skipped):

| Emoji    | Name      |
| -------- | --------- |
| 👨‍👩‍👧‍👦 | Family    |
| 👩‍💻     | Developer |

This is an honest limitation of terminal display technology, similar to what other tools like markdownlint experience.

Fix Behavior¶

When applying automatic fixes (rumdl fmt), this rule:

1. Calculates proper display width for each column using Unicode width measurements
2. Pads cells with trailing spaces to align columns
3. Preserves cell content exactly (only spacing is modified)
4. Respects alignment indicators in delimiter rows:
5. :--- → Left-aligned
6. :---: → Center-aligned
7. ---: → Right-aligned
8. Auto-compacts tables exceeding max-width to prevent line length violations
9. Skips tables with ZWJ emoji to prevent alignment corruption
10. Masks inline code blocks to avoid treating code pipes as table delimiters

Common Use Cases¶

Recommended Configuration (Conservative)¶

For most projects, start with this conservative configuration:

[MD013]
line-length = 100

[MD060]
enabled = true        # Enable table formatting
style = "aligned"     # Align columns for readability
max-width = 0         # Auto-compact tables exceeding 100 chars

This provides readable tables without creating excessively long lines.

Strict Compact Mode¶

For projects preferring minimal formatting:

[MD060]
enabled = true
style = "compact"

Allow Any Style¶

To check without enforcing:

[MD060]
enabled = true
style = "any"  # No enforcement, preserves existing formatting

Unlimited Table Width¶

For projects that want aligned tables without any width limits:

[global]
disable = ["MD013"]  # No line length checks = no table compacting

[MD060]
enabled = true
style = "aligned"
max-width = 0  # Will be unlimited since MD013 is disabled

Or, if you want MD013 for code but not tables:

[MD013]
line-length = 80
tables = false  # Skip table line length checks

[MD060]
enabled = true
style = "aligned"
max-width = 0  # Will be unlimited since MD013.tables = false

Integration with Other Rules¶

MD013 (Line Length):

• MD060's max-width = 0 uses smart inheritance from MD013
• If MD013 is disabled or tables = false, tables have unlimited width (no auto-compact)
• If MD013 is enabled with tables = true, tables are auto-compacted at line-length
• Can override with explicit max-width value to ignore MD013 entirely

MD056 (Table Column Count):

• MD056 validates column count consistency
• MD060 formats tables after MD056 validates structure
• Use both rules together for comprehensive table linting

Performance Notes¶

Table formatting is computationally intensive due to Unicode width calculations. MD060 is optimized with:

• Efficient Unicode width caching
• Early bailout for complex Unicode sequences
• Parallel processing in fix mode (when multiple tables exist)

For large documents with many tables, expect formatting to take a few hundred milliseconds.

Rationale for Default Disabled¶

MD060 is disabled by default because:

1. Large diffs: Enabling on existing codebases can produce massive formatting changes
2. Opt-in adoption: Teams should consciously decide to adopt table formatting
3. Performance: Unicode width calculations add overhead
4. Conservative approach: Matches rumdl's philosophy of opt-in for aggressive formatting

We recommend enabling MD060 for new projects or when doing a formatting cleanup pass.

See Also¶

• MD056 - Table Column Count (validates table structure)
• MD013 - Line Length (works with MD060's auto-compact)
• MD055 - Table Pipe Style (validates pipe placement)