Formatting standards ·
Why structured Markdown tables beat proprietary spreadsheets in docs
A Markdown table is readable in diffs, greppable, and license-free. An .xlsx is a zip of XML that hides in binary review. For API field lists, HTTP status matrices, and config flags, GFM wins. For accounting workbooks, it does not. Convert CSV to Markdown locally when the destination is a repo.
Diffability and PR review
A one-cell change is one line in git. xlsx diffs are noise. That is why runbooks moved to docs-as-code.
GFM alignment row
| --- | ---: | :---: | sets left, right, center. The separator row is required. Leading/trailing pipes are conventional.
Limits
No types, no formulas, poor accessibility if you dump HTML without scope. Convert to HTML tables with thead for docs sites.
CSV to Markdown in the browser
Papaparse then join pipes. Same in-memory story as other data tools. SQL pretty-print is the sibling for queries in the same README.
Accessibility
Rendered HTML needs headers. Raw Markdown in GitHub is acceptable for engineers; public docs should compile to semantic tables.
Frequently asked questions
Do Markdown tables support merged cells?
GFM does not. If you need merges, you wanted a spreadsheet or HTML.
How do you escape pipes in cells?
Use \| or HTML entities. Inconsistent escaping is the usual render bug.
When is Markdown the wrong format?
Numeric models, pivot tables, and anything over a couple of hundred rows. Keep those as CSV/JSON.