Markdown Tables That Survive a PDF Page
A table that looks fine in a Markdown preview can still fall apart on an A4 page. Here is what breaks, and what to check before you export.
このページの目次
A table is a grid, a page is a box
Markdown tables are described as rows and cells. A PDF page is a fixed width with margins. Those two models agree until a row gets wide enough to need more space than the text block allows.
Every table export problem comes from that collision: the table wants to be as wide as its content, the page insists on 170mm.
The three things that break
| What goes wrong | What you see | What to check |
|---|---|---|
| Wide tables | Columns run past the right margin, or the last column disappears | Does the exporter measure the printable width or just shrink the font |
| Merged headers | colspan / rowspan collapse into a flat grid |
Does it accept HTML tables, or only pipe tables |
| Long tables | The header row appears once, then page two is a wall of numbers | Do headers repeat on every page |
The first one is the most common. The second one is the most annoying, because a table with a merged header is often the only way to express two-level groupings.
A wide table, unchanged
This is seven columns of the kind that shows up in quarterly reports:
| Region | Q1 | Q2 | Q3 | Q4 | Target | Status |
|---|---|---|---|---|---|---|
| North America | 1,240 | 1,318 | 1,402 | 1,511 | 1,500 | Ahead |
| EMEA | 860 | 904 | 951 | 1,020 | 1,000 | Ahead |
| APAC | 512 | 548 | 587 | 640 | 700 | Behind |
| LATAM | 210 | 236 | 260 | 288 | 300 | Behind |
At A4 width with 16mm margins, seven columns of four-digit numbers fit. Eight columns of prose do not, and that is where scaling or rebalancing has to happen.
Merged headers are HTML, and that is fine
Markdown has no syntax for colspan. The practical answer is a small HTML table inside the Markdown, which every serious converter should accept:
| Region | 2025 | 2026 | ||
|---|---|---|---|---|
| Q1 | Q2 | Q1 | Q2 | |
| North America | 1,240 | 1,318 | 1,402 | 1,511 |
| EMEA | 860 | 904 | 951 | 1,020 |
If a converter rejects this, it will also drop captions, alignment and anything else that lives outside the pipe-table grammar.
Five failures we reproduced
Each case below was exported on a real machine with the default engine at A4 with 16 mm margins, then measured inside the resulting PDF. None of them raises an error — that is exactly why they are worth knowing.
| What you write | What the PDF contains | What to change |
|---|---|---|
| A row with more cells than the header | The extra cells are gone. A four-cell row under a three-column header prints three cells; the fourth never reaches the page. | Keep every row the same width, or give the extra value its own column. |
A cell containing an unescaped | | The row splits early and the last cell is dropped. | Escape it: a\|b prints as a|b. |
A table without the | --- | separator row | No table at all — the pipes and the rows print as ordinary lines of text. | Keep one separator row with one cell per column. |
| A table pasted into a list item | It becomes list text, with the first cell as the bullet; the grid disappears. | Un-indent the table. A blockquote is fine; a list item is not. |
| Forty columns | Nothing is clipped, but the glyphs shrink to roughly 4 pt against 14 pt body text — present on the page, unreadable on paper. | Split the table, or move it to a landscape appendix. |
Four behaviours survive the same measurement, which is why the checklist above is short: the header row repeats on every page of a 60-row table, a ten-column prose table keeps all fifty cells and stays inside the page, a 120-character unbroken URL wraps instead of overflowing, and a right-aligned numeric column really does align on the right edge.
A short checklist
- Export the widest table you actually have, not a three-column sample.
- Look at the right margin. A table that is clipped is worse than one that is scaled down.
- Check page two of a long table. If the header is missing, the table is unreadable in print.
- Search for a caption in the PDF. If the find box cannot locate it, the caption was dropped.
How to try it with your own table
The table sample below walks through the same checks. If you want a document that already has a wide table and a merged header, open the table sample and export it before pasting your own.
For tables combined with formulas or diagrams, use the same editor and review the PDF feature set.
What we do not claim
Very wide tables still have a limit: past a certain column count, scaling makes the text unreadable and the honest answer is a landscape page or an appendix. Merged cells and captions are supported in the HTML table form shown above; plain pipe tables cannot express them, because the Markdown syntax has no place to put them.
This article is one part of a wider checklist: Markdown to PDF: tables, diagrams and equations covers tables, diagrams and equations together, and how to decide what to fix first.
同じレンダラーをすぐに試せます。動作するサンプルを開いて書き出し、そのあと自分の Markdown を貼り付けてください。