Markdown Tables from Excel — Pipe Escape Hell
You copy a comparison matrix from Excel, paste into a pull request, and GitHub renders a jagged ruin: columns shifted, a header that swallowed half the row, and one cell that contained a | character acting like an extra delimiter. Markdown tables are deliberately simple — which means special characters in cell text punch above their weight.
Anatomy of a GFM table
| Feature | Free | Pro |
| --- | ---: | ---: |
| Seats | 3 | 25 |
| SSO | no | yes |- Row 1: headers
- Row 2: alignment markers (
---left,:---left,---:right,:---:center) - Following rows: cells separated by
|
Leading and trailing pipes are conventional. Inner pipes always mean “new column” unless escaped.
Spreadsheet → Markdown without tears
- Clean the sheet — no merged cells; they do not survive. Split them first.
- Copy the range — Excel/Sheets usually puts tabs between columns on the clipboard (TSV).
- Convert TSV to pipes — replace tabs with
|, add|at line starts/ends, insert the separator row. - Escape cell pipes — replace
|in data with\|for GitHub. - Preview — open the PR “Files changed” or a local GFM preview before you ask for review.
Newlines inside a cell are another trap. GFM tables are single-line rows; put <br> only if your renderer allows HTML in tables, or split into two rows.
Characters that deserve a pre-flight check
| Character | Risk | Mitigation |
|---|---|---|
| | Extra columns | Escape as | |
| backticks | Code spans eating pipes | Prefer indent/code block outside table |
| leading/trailing spaces | Usually fine | Avoid relying on them for alignment |
| Unicode dashes | Look like --- separators | Use ASCII hyphens in the separator row |
Numeric columns: right-align with ---: so versions and prices skim cleanly.
Platform quirks worth remembering
- GitHub — GFM tables; HTML allowed in many cases; wide tables horizontal-scroll on the site.
- Notion — Paste often becomes a Notion table (good). Exporting Notion → Markdown can reintroduce pipe issues.
- Static site generators — Some Markdown engines need a plugin for tables; confirm locally.
- Jira / older wikis — Different dialects; do not assume GFM.
When docs must stay identical across tools, prefer CSV attachment + short Markdown summary over a 20-column pipe monster.
Review habits for doc PRs
- Diff the raw
.md, not only the rendered page — escaped pipes are easy to miss visually. - Keep header labels short; wrap meaning in a footnote under the table.
- For huge matrices, link a spreadsheet and keep Markdown to the decision-relevant subset.
Convert paste-friendly grids with markdown-table when you want columns escaped and separator rows inserted without hand-counting pipes — especially after a sheet export that includes version strings like v1|beta.
A small example with an escape
| Command | Meaning |
| --- | --- |
| `a \| b` | pipe in prose |
| select * | not a pipe issue |Ship tables that survive copy-paste from finance sheets and engineering trackers alike: TSV in, pipes out, escapes verified, preview on the platform that will render the final doc.