docs-md-table-formatting

name	docs-md-table-formatting
description	Use when creating, editing, or reformatting markdown tables in any document, when table columns look misaligned, or when reviewing markdown files that contain tables

Markdown Table Formatting

Overview

Rules for consistently formatted, readable markdown tables. Misaligned tables are hard to scan in source view and may trigger linter warnings.

A reformat-md-tables PostToolUse hook auto-realigns tables in every *.md file on each Write/Edit, so tables Claude writes stay aligned with no manual step. To bulk-reformat a tree by hand or in CI, run this skill's reformat_tables.py -r <dir> (see Programmatic Reformatting below).

Rules

1. Pad all cells to column width

Every cell in a column must be padded with trailing spaces to match the widest content in that column.

# BAD  -  unpadded
| Name | Value |
|------|-------|
| Type | Settable |
| Value | String (colon-separated list) |

# GOOD  -  padded to widest content per column
| Name  | Value                         |
|-------|-------------------------------|
| Type  | Settable                      |
| Value | String (colon-separated list) |

2. Separator dashes touch the pipes

No spaces between pipes and dashes in the separator row. Dash count = column width + 2 (matching the space-padded content cells).

# BAD  -  spaces around dashes
| Name  | Value    |
| ----- | -------- |

# GOOD  -  dashes touch pipes
| Name  | Value    |
|-------|----------|

3. Content cells have exactly one space padding

Each content cell has exactly one space after | and one space before |.

# BAD  -  inconsistent spacing
|Name  |Value                         |
| Name  |Value                         |

# GOOD
| Name  | Value                         |

4. Trailing pipe required

Every row ends with a closing |.

5. Column count is consistent

Every row (header, separator, data) must have the same number of columns.

6. Reformat tables inside blockquotes

Tables inside blockquotes (> | ... |) are reformatted using the same rules. The blockquote prefix is preserved.

7. Reformat tables inside markdown fenced code blocks

Tables inside fenced code blocks tagged with markdown or md are reformatted using the same rules as tables in the document body. Tables in other code blocks (e.g., python, json) are left untouched.

Quick Reference

| header1 | header2 long name |      <- content padded to widest per column
|---------|-------------------|      <- dashes touch pipes, width = content + 2 spaces
| short   | value             |      <- trailing spaces to fill column width
| longer  | x                 |      <- every cell padded

Programmatic Reformatting

For files with many tables, use reformat_tables.py in this directory rather than manual edits:

# Reformat all *.md files under a specific directory (recursive).
# Pass the directory explicitly - a bare -r reformats the CURRENT directory,
# which is this skill's own dir if you cd'd here to run the script.
python3 reformat_tables.py -r docs/

# Reformat specific files
python3 reformat_tables.py file.md [file2.md ...]

# Dry-run  -  reports what would change, exits 1 if changes needed
python3 reformat_tables.py --check -r

# Create .bak backup before writing
python3 reformat_tables.py --backup file.md

Safe by design: reformats tables inside blockquotes and ```markdown/```md fenced code blocks, skips all other fenced code blocks, preserves alignment markers (:---, :---:, ---:), handles pipes inside backtick spans, and bails on tables with inconsistent column counts.

Editing tables via JSON (tablekit.py)

reformat_tables.py re-aligns tables in place; when you need to CHANGE a table's content (add/remove/reorder rows or columns, retarget alignment) without hand-padding every cell, use tablekit.py in this directory. It round-trips a table through JSON: read it, edit the JSON, and re-emit it fully aligned. replace splices the rendered table back into the file at its original position, leaving surrounding prose untouched.

# Read the Nth table (0-based) to JSON: {headers, alignments, rows}
python3 tablekit.py read FILE.md --index 0        # omit --index to list all tables (with line spans)

# Render a table's JSON (from stdin) to aligned markdown
python3 tablekit.py render < table.json

# Edit the JSON in a pipeline, then splice it back into the file (or --stdout to preview)
python3 tablekit.py read FILE.md --index 0 \
  | jq '.rows += [["new", "row"]] | .alignments = ["left","right"]' \
  | python3 tablekit.py replace FILE.md --index 0

alignments values are left / right / center / none. rows is a list of cell-lists; ragged rows are padded to the column count on render. Stdlib only; a literal | in a cell round-trips (escaped as \| in the markdown, unescaped in the JSON).