TL;DR — Markdown tables usually break in PDF for boring, predictable
reasons: the content is too wide, the export path is just "print the page," or
the renderer does not treat tables as first-class layout. Use real
GitHub Flavored Markdown tables, keep cells
tight, avoid giant unbroken strings, and use a renderer that treats
table-splitting as a document-layout problem rather than a browser accident.
Tables are one of the first things to look good in Markdown preview and one of
the first things to go bad in exported PDFs.
You have probably seen some version of this:
- the table gets cut awkwardly across pages,
- the header ends up separated from its rows,
- one long cell blows out the layout,
- the PDF becomes tiny and unreadable,
- or the "table" turns into something that feels like a screenshot of a table
rather than a real document structure.
That is not random. It usually comes from a few specific causes.
Why tables fail more often than paragraphs
Paragraphs can reflow. Tables cannot.
A paragraph has a lot of flexibility: wrap lines, move to the next page, and
continue. A table has a harder job:
- column widths need to make sense together,
- headers should stay attached to rows,
- one cell can force the whole table wider,
- and page breaks need to happen at sensible row boundaries.
So when the export pipeline is simplistic, tables expose the weakness fast.
The three common failure modes
1. The table is too wide for the page
This is the most common problem. One or two wide columns, long URLs, long inline
code fragments, or very verbose prose can force the table beyond a comfortable
page width.
Typical culprits:
- long unbroken code identifiers,
- long URLs inside cells,
- too many columns,
- and cells that really should have been lists or paragraphs instead.
If the table is fundamentally wider than the page, no exporter can magically
make it elegant without tradeoffs.
2. The export path is really just browser print
Many "Markdown to PDF" flows are basically:
- Render HTML.
- Ask the browser to print it.
- Hope for the best.
That can be fine for simple pages, but it is not the same as deliberate
document layout. Browser print is often not opinionated enough about keeping a
table together, preserving the connection between headers and rows, or handling
page boundaries cleanly.
That is why a table can look okay on screen and then feel unstable in PDF.
3. The renderer does not treat the table as a layout object
Some exporters handle tables almost like decorated text blocks. That works until
the content becomes realistic.
A better PDF path treats the table as a real document element with rules about:
- column sizing,
- row flow,
- page boundaries,
- and whether the table should remain whole when it still fits on a fresh page.
If those rules are weak, table output usually looks weak too.
A simple table example
This kind of table is common in technical docs:
| Option |
Best for |
Main tradeoff |
| PDF |
Final delivery |
Harder to comment inline |
| DOCX |
Review and edits |
Less fixed layout |
| YAML |
Machine inspection |
Not a presentation format |
This is small and clean. Most renderers should handle it well.
Now compare that to a riskier table shape:
- one column contains longer prose,
- another contains a long inline code identifier,
- and another contains a raw URL that does not wrap nicely.
That combination makes the layout much more fragile.
Here is the raw Markdown source for the riskier version:
| Item | Details | Link |
|---|---|---|
| Parser | Long inline code like `very_long_identifier_that_never_wraps_cleanly` widens cells fast | https://example.com/really/long/path |
| Renderer | Dense prose plus raw links make narrow columns harder to fit | https://example.com/another/long/path |
The second example is much more likely to create ugly PDF output because the
cells fight the page width.
How to fix the problem before export
You usually do not need a completely different tool. First fix the content
shape.
Keep cells short
Treat tables as compact comparison structures, not as mini essays. If a cell
needs multiple sentences, the information may belong below the table instead.
Avoid long unbroken strings
Long inline code, long URLs, and long path names are frequent offenders. If the
table is mostly code samples or raw URLs, consider moving those out of the table
and linking or referencing them nearby.
Reduce the number of columns
Wide tables become brittle fast. If a table has too many columns, split it into
two smaller tables or convert part of it into bullets.
Use real Markdown tables
Prefer standard Markdown tables over pasted complex HTML when the information is
truly tabular. A standard Markdown table is easier for a Markdown-aware
renderer to interpret consistently.
Accept that some tables really must split
There is a difference between:
- a table that could fit on one fresh page and should stay together, and
- a table that is taller than one page and must split somehow.
A good renderer should distinguish between those two cases.
Where depapel helps
This is one of depapel's stronger product-backed claims.
In this repo, PDF table behavior is treated as a hard regression boundary:
- if a table fits on one fresh page, it should stay on one page,
- and only tables taller than one page may split across pages.
That sounds small, but it is exactly the kind of rule that separates "print the
page" output from deliberate document output.
So if the table is reasonably authored, depapel
is built to give it a better chance of surviving export cleanly.
When the table should not be a table
This is the most useful editorial fix.
If you are forcing very long prose into multiple columns just because the source
started as a comparison, try one of these instead:
- a short table plus detailed notes underneath,
- a heading per option with bullets,
- or a two-column table instead of a five-column one.
Many bad PDF tables are really a document-structure problem before they are a
renderer problem.
Final rule of thumb
Markdown tables work best in PDF when they are:
- narrow enough for the page,
- concise enough to stay readable,
- authored in standard table syntax,
- and exported through a renderer that treats tables as layout, not as an
afterthought.
If you do those four things, table output gets much more predictable.
And if a table still looks bad, the first question should not be "why is PDF
hard?" It should be "is this actually a good table for a page-sized document?"
Please enable JavaScript to use depapel.