Markdown tables that survive the page break

It is a small failure with a disproportionate effect. Three columns of numbers with no labels above them are not hard to read — they are impossible to read, and the reader has to page backwards to find out what they are looking at.

What actually goes wrong

A Markdown table looks like this, and the second line is doing more work than it appears to:

| Plan       | Exports | Pages |
| ---------- | ------- | ----- |
| Free       | 20      | 40    |
| Essentials | ∞       | 80    |

The dashes are not decoration. They mark the row above as a header, and a correct converter turns that into a <thead> element distinct from the <tbody> beneath it. That distinction is the entire mechanism: a paged renderer repeats <thead> on every page a table spans, and it can only do that if something told it which row the header was.

When headers vanish, it is nearly always one of three things:

1. The converter emitted no `<thead>`, so every row is body content and there is nothing to repeat.
2. The renderer does not implement header repetition. Browsers have supported it for printed tables for years, but a naive HTML-to-PDF pipeline can still lose it.
3. The table is inside something that cannot break — a wrapper with overflow set for horizontal scrolling, which makes sense on screen and turns the table into one indivisible block on paper.

Writing tables that convert cleanly

Always include the header row

Markdown has no way to express a table without one. If your data genuinely has no headers, you still need the separator line — give the columns short labels rather than leaving them blank, because empty header cells read as a rendering fault to anyone who sees them.

Keep cells short

A table cell holding a full paragraph is a layout problem in any medium and a much worse one on a fixed page, where there is no scrolling to absorb it. If a cell needs a paragraph, the table is really a list of sections and should be written as one.

Count your columns before you count your words

On A4 with normal margins you have roughly 16 centimetres of usable width. Four columns of prose is generally the practical limit; beyond about six, no amount of clever rendering will save it. Consider whether the table should be rotated — attributes down the side, items across the top — which usually reduces the column count and reads better anyway.

Do not align with spaces

Padding cells so the pipes line up in your editor is pleasant and completely invisible in the output. It is fine, but do not spend time on it, and do not let it stop you from editing a table because realigning it is tedious.

| Format | Pages | Best for |
| --- | --- | --- |
| PDF | Fixed | Print, handouts |
| EPUB | Reflowable | E-readers, stores |

When the table is too wide anyway

Sometimes the data genuinely does not fit. The options, roughly in order of how well they work:

• Split it into two tables along a natural seam. Two readable tables beat one unreadable one, always.
• Transpose it. Ten rows and three columns is a table; three rows and ten columns is a wall.
• Turn it into a list. Where each row is really "one thing and its properties", a heading with a short list under it is often clearer than the table ever was.
• Shrink the type for that table only. A last resort, and only for reference material nobody reads straight through.

Checking before you ship

The failure only shows up when a table happens to land near a page boundary, which means it can survive every draft and appear the week you publish, after an edit three chapters earlier pushed everything down by half a page.

So check the output rather than the source: export, and look at every table in the finished file. If your tool has a paginated preview, look there — the point of a preview that paginates with the same rules as the export is that a table crossing a page on screen is a table crossing a page in the file.

In bukpress, tables written as plain Markdown get a real header row, and when one runs past the bottom of a page that header repeats at the top of the next. It is not a setting; it is what a table crossing a page is supposed to do.

For the wider version of this problem, how to control page breaks in Markdown covers the rules that keep headings with their sections and lines from being stranded.