markdown-tables

Markdown Table Formatting Skill

Markdown tables MUST use fixed-width columns with space padding. This is mandatory for readability in plain text editors and diffs.

Correct vs Incorrect Format

Correct: Fixed-width columns with padding

| Size     | succinctly          | jq                  | Speedup    |
|----------|---------------------|---------------------|------------|
| **10KB** | 2.2 ms (4.3 MiB/s)  | 4.1 ms (2.3 MiB/s)  | **1.86x**  |
| **1MB**  | 24.5 ms (33 MiB/s)  | 44 ms (18 MiB/s)    | **1.79x**  |

Incorrect: Unpadded columns

| Size | succinctly | jq | Speedup |
|------|------------|-----|---------|
| **10KB** | 2.2 ms (4.3 MiB/s) | 4.1 ms (2.3 MiB/s) | **1.86x** |

Column Width Rules

1. Measure the widest content in each column (including header)
2. Pad all cells to match the widest cell in that column
3. Use spaces for alignment, not tabs
4. Align text left, numbers can be right-aligned for decimals
5. Leave one space after | and before | for readability in data rows
6. Separator row has NO spaces - format as |------|---------| with dashes matching column widths
7. Empty cells use single dash "-" padded with spaces: | - |

Formatting Algorithm

For each column:
  1. width = max(len(cell) for cell in column)
  2. width = max(width, 3)  # Minimum 3 chars for separator

For each row:
  1. For each cell:
     - Pad content to column width
     - Add single space before and after content
  2. Join cells with '|' delimiter
  3. Add '|' at start and end

Bold Text in Tables

When using bold (**text**) in table cells:

Spaces must be OUTSIDE the bold markers, not inside:

<!-- CORRECT: Spaces outside ** -->
|   **59.6ms** |

<!-- WRONG: Spaces inside ** (markdown won't render bold) -->
| ** 59.6ms** |

This is important for right-aligned numeric columns where padding is added.

Alignment Markers

Alignment	Separator Format	Example
Left	`	----------
Right	`	---------:
Center	`	:--------: