markdown tables without pain

For a long time I avoided markdown tables because editing them was awful. The columns drift, the pipes don't line up, and adding a row means reformatting everything. Three things fixed this for me.

1. stop aligning the pipes

Markdown doesn't care about column alignment in the source. This is valid:

| name | type | notes |
| --- | --- | --- |
| port | int | listening |
| tls | bool | required |

Rendered output is identical to the painstakingly aligned version. Every editor plugin that "auto-aligns" tables is solving a problem you don't have.

2. use a formatter only when you output

If the table is going somewhere that renders markdown (GitHub, a note app, a static site), leave it ugly in source. If you need aligned source for some reason, run prettier --parser markdown once at the end.

3. CSV when the table gets big

Once a table has more than ~8 rows or ~5 columns, markdown stops being the right format. Move to a CSV file, reference it, or render it from data. I've rewritten too many 30-row "markdown" tables after regretting the initial choice.

one more thing

GitHub-flavored markdown supports alignment with :---: and ---:. I use left-align by default (no colons). Centering numeric columns is tempting but rarely helps readability.