Align Markdown table columns and rebuild separator rows so README files, issue comments and changelogs stay readable in source form. This is a text aligner, not an HTML renderer.
Algorithm sketch
- Split lines into cells (backslash-pipe escapes supported).
- Detect a delimiter row; otherwise synthesize a left-aligned one.
- Pad each column to the max cell length (minimum width respected for delimiters).
- Re-emit header, delimiter and body.
You need at least one header row and one body row. Status text reports row and column counts on success.
Workflow tips
Right-align numeric columns in the separator so source diffs stay tidy. Keep CSV as the source of truth when tables summarize exports; re-run the formatter after column edits. Wide Unicode and emoji may disagree with terminal display width because padding uses string length, not East Asian Width—tweak manually if a column looks off.
Avoid nested HTML tables and multiline cells; they are out of scope. Escape literal pipes in cells. After formatting, paste into the target Markdown surface and confirm the rendered table still matches intent.
Why source alignment still matters
Rendered Markdown hides ragged columns, but reviewers edit the source. Misaligned pipes make drive-by edits break unrelated cells. Running this formatter before you open a PR reduces comment noise and keeps changelog tables maintainable.
Recommended habit: author the table loosely, format once, then make surgical cell edits without reflowing every row by hand. When you insert a column, add the header and cells first, then format again so the separator grows with the new width.
Content policy for tables
Tables are snapshots, not databases. If the upstream data lives in CSV, keep CSV canonical and paste a formatted Markdown excerpt into docs. Otherwise the wiki table drifts from reality within a week. Numeric columns belong right-aligned; names stay left-aligned; status enums can be centered if you want visual scanning.
Escaping: a literal pipe inside a cell must be written as backslash-pipe or the splitter thinks a new column started. After formatting, skim the rendered preview on GitHub or your static site to ensure emoji and Hangul columns still look acceptable despite width heuristics.
PR description pattern
Many teams paste comparison tables into pull requests. Draft the table in a scratch buffer, format it here, then paste into the PR body. Reviewers scanning the source of the comment see aligned columns and spend attention on the values instead of the pipes.
If a cell must show a regex that includes |, escape it. If a cell needs a line break, rethink the table—multiline cells are not supported and will confuse both this formatter and many renderers.
Keep a short before/after snippet in your team wiki so newcomers see why the formatter exists and when to re-run it after edits.
FAQ
Do I need a separator row?
No. If it is missing, the first row becomes the header and a left-aligned separator is inserted.
How do I set alignment?
Use :--- left, --- or :--- left default, ---: right, :---: center in the separator row.
How do I put a pipe inside a cell?
Escape it as a backslash-pipe sequence so the parser does not start a new cell.
Is anything uploaded?
No. Only the table text is aligned locally.