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:

Revenue by region (USD thousands)
Region20252026
Q1Q2Q1Q2
North America1,2401,3181,4021,511
EMEA8609049511,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 writeWhat the PDF containsWhat to change
A row with more cells than the headerThe 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 rowNo 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 itemIt 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 columnsNothing 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

  1. Export the widest table you actually have, not a three-column sample.
  2. Look at the right margin. A table that is clipped is worse than one that is scaled down.
  3. Check page two of a long table. If the header is missing, the table is unreadable in print.
  4. 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.