How to Fix Broken or Overflowing Markdown Tables

Fast fixes for Markdown tables that overflow PDFs

Before shrinking type with CSS, fix a table that runs off the right edge in this order:

1. Replace visible URLs with labels and move long code or prose outside the table.
2. Remove low-priority columns and shorten headings.
3. Use landscape only for wide tables, or split the table by meaningful groups.
4. Check the right edge and page boundaries in both print preview and the saved PDF.

Avoid-break-inside rules suit only short tables. A taller table can leave a large gap or move entirely to the next page, so split long tables instead.

Separate syntax problems from layout problems

A Markdown table can fail because it is not parsed as a table or because the rendered table is wider than its HTML or PDF container. Start with a header, a separator row, and consistent column counts.

Tables are often a GFM extension rather than a universal Markdown feature. Confirm that the destination supports them. Escape a literal pipe where supported, and keep formatting consistent across the document.

Long URLs, paths, code, and unbroken identifiers can force a column wider. Replace a visible URL with a descriptive link, move details below the table, or split one table into smaller comparisons. For a PDF, remove columns before shrinking text; landscape orientation is another option.

<br> may create line breaks inside GFM cells, but sanitizers can remove raw HTML. A cell containing several paragraphs is usually a sign that the explanation belongs outside the table.

Short tables can be kept together across a page break, but a table longer than one page must split. Divide it at meaningful boundaries and verify the last row, borders, links, and embedded images in the saved PDF.

Run a three-minute diagnosis

Copy only the failing table into a small Markdown file and replace every value with short text. If it still renders as plain pipes, fix syntax or confirm GFM table support. If the short version works and the original overflows, the cause is content width: a URL, code token, file path, or too many columns. If the isolated table works but fails inside the full document, inspect page margins, surrounding raw HTML, and print scale.

A valid GFM table needs a header row, a separator row, and the same logical column count in every row. Keep leading and trailing pipes consistently even when a parser considers them optional. Escape a literal pipe where supported, and avoid placing multi-line block Markdown inside a cell.

Fix width without destroying readability

Do not begin by shrinking the font. Remove low-priority columns, move explanations below the table, split unrelated comparisons, shorten headings, and replace visible URLs with descriptive links. Only then consider a modest type-size reduction. A PDF that technically fits but cannot be read at 100% zoom is not fixed.

Use tables for comparison, not for storing paragraphs. If a cell needs several sentences, assign a short identifier in the table and explain it in a section underneath. Put units and effective dates in headers so values remain understandable after a table is split.

Handle long tokens and code safely

URLs, hashes, API keys, UUIDs, and filesystem paths do not have natural wrapping points. Prefer a human-readable link label. For identifiers that must remain visible, move them to a code block outside the table or add safe wrapping in the export stylesheet when you control it. Never insert spaces into a value when those spaces would change the identifier.

Plan long tables for pagination

“Avoid break inside table” is suitable only when the whole table fits on one page. A table taller than the printable area cannot obey that rule. Split it by category, repeat context in each section heading, and verify that no row is stranded without an explanation. Moving a page break immediately before a short table often produces a cleaner result than squeezing it into the remaining space.

PDF table preflight checklist

• Confirm the table is parsed in preview.
• Count columns and inspect literal pipe characters.
• Replace long visible URLs with labels.
• Remove or relocate prose-heavy columns.
• Inspect the right edge at 100% zoom.
• Check every page boundary in a long table.
• Verify links, borders, images, units, and the final row.
• Open the saved PDF, not just the browser preview.

See line breaks inside Markdown table cells when a compact cell genuinely needs two short lines.

Frequently asked questions

Why does the table work on GitHub but not elsewhere?

Pipe tables are commonly provided by GitHub Flavored Markdown rather than every Markdown parser. Confirm that the target enables GFM. If it does not, use supported HTML, a list, or provide the data separately as CSV.

Is horizontal scrolling acceptable?

It can be acceptable for responsive HTML, but a PDF has a fixed page width and cannot rely on scrolling. Design the table for the PDF's printable width, then verify that the same structure remains understandable on smaller screens.