---
name: markdown-table-formatting
description: Use after writing or editing any markdown file - ensures tables have aligned columns with consistent widths
---

# Markdown Table Formatting

## Overview

After writing markdown, make a second pass to align table columns. Every cell in a column should have the same width (padded with spaces).

## When to Use

**After writing/editing any `.md` file that contains tables.**

## The Rule

```
SECOND PASS ON ALL MARKDOWN TABLES
```

**Bad** (minimal separators):
```markdown
| Component | Approach | Rationale |
|---|---|---|
| **Terraform** | Human-coded | Core learning |
```

**Bad** (one line wider than others):
```markdown
| Component                   | Approach                    | Rationale        |
|---|---|---|
| **Terraform** | Human-coded | Core learning |
```

**Bad** (separator doesn't match content):
```markdown
| Component                   | Approach                    | Rationale        |
|-----------------------------|-----------------------------| -------------|
| **Terraform**               | Human-coded                 | Core learning |
```

**Good** (all rows aligned, including separator):
```markdown
| Component                   | Approach                    | Rationale        |
|-----------------------------|-----------------------------| -----------------|
| **Terraform**               | Human-coded                 | Core learning    |
| **React Native components** | Human-coded, Claude prompts | Mobile dev focus |
```

## Formatting Rules

1. Find **longest cell** in each column (including header)
2. **Pad ALL cells** to that width with trailing spaces
3. **Separator dashes** must match column width exactly
4. **Single space** after `|` and before closing `|`

**Exception:** If aligned table would exceed **300 characters wide**, skip formatting for that table. Readability trumps alignment for very wide tables.

## Quick Check

After writing markdown:
1. Find all tables
2. Measure longest cell per column
3. Pad ALL rows (header, separator, data) to match
4. Verify visually - columns should form straight lines