Why Markdown PDFs and Print Look Broken — Causes and Fixes

Fix common Markdown-to-PDF and print issues—margins, breaks, missing backgrounds, font substitution, overflowing tables. Includes a triage checklist and browser comparison notes.

After PDF export or browser print, you often hear: "It looked fine on screen, but the table overflows," "A heading splits across pages," "Fonts changed," or "Background colors vanished." Causes cluster into three areas: how HTML/CSS is interpreted, paper, margins, and the print engine, and content width/length, plus gaps between screen CSS and print CSS.

Fastest way to diagnose print and PDF layout problems

Open print preview, lock the paper size, orientation, and scale, then test one symptom at a time. Changing several settings together makes the actual cause hard to find.

Symptom	First action	Detailed guide
Table runs off the right edge	Remove columns or switch to landscape; replace visible URLs with labels	Fix broken or overflowing Markdown tables
Heading or table splits badly	Check break positions and keep-together settings	Control Markdown PDF page breaks
Margins are too wide or text is too small	Check that tool and print-dialog margins/scale are not both shrinking content	Adjust Markdown PDF margins
Background colors disappear	Enable “Background graphics” in the print dialog	Checklist below

Save a new PDF after each change, then inspect the affected page and its neighbors. Margin and font changes also move page breaks.

What goes wrong, by symptom

Awkward page breaks — Markdown has no native page; the engine chooses breaks for you. To force "break before this heading" or "keep this table on one page," use CSS print properties or visual break controls in your tool (see the page-break article). With no policy, you inherit the browser/PDF engine's defaults—often misaligned with intent.

Margins and fonts feel wrong — Typical pattern: @page margin, body padding, and the print dialog's margin preset all apply at once and stack or override each other. If screen rules and @media print diverge, the look can change completely.

Tables and code overflow horizontally — Long URLs, identifiers, or tabs that do not wrap become one ultra-long line. Paper width is finite—fix in the source (manual breaks) or via wrapping, font size, max width in CSS/tool settings.

Images too large or small — Confirm max-width: 100% (or equivalent). A very large source bitmap (e.g. Retina screenshots pasted as-is) can dominate a printed page.

When preview looks fine but print/PDF does not

@media screen vs @media print often differ: full-width layouts may become narrower columns in print; backgrounds and borders may disappear unless print background graphics is on. Devtools may emulate print styles, but trust the real print preview for final layout.

Quick checklist

Double margins — "Minimal/none" in the dialog plus CSS @page / body margins.
Bad breaks — Through headings, or inside tables and code blocks.
Backgrounds — Many browsers skip backgrounds unless explicitly allowed.
Fonts — Print may substitute families, shifting line breaks.
Zoom and paper — Not 100% zoom or wrong paper size skews scale.

Chromium, Firefox, and Safari use different print engines—same HTML, slightly different breaks/fonts. For internal templates, write a recommended browser and Save-as-PDF steps in the README to cut support noise.

Combine fixes

First, encode break rules: e.g. always break before h1, never inside tables/code—set in layout, then fine-tune in preview. Second, set margins, fonts, line height explicitly and check print preview. Third, PDF through the same path as preview (e.g. browser Save as PDF) so CSS application stays familiar. When the tool exposes layout settings, align margins and typography before tweaking Markdown—most "broken" exports are under-specified, not bad prose. For paper submissions, print a physical proof when it matters.

Adjust only the pages that fail

Export once with the default layout, then adjust only the pages that fail. Repeated global changes to margins or fonts will move pagination on pages that were already correct. Apply break-after: avoid to headings and break-inside: avoid to short tables or code blocks only where needed. Never keep together an element taller than one page. For formal delivery, review the cover, TOC, fonts, and the entire print preview before release.

Troubleshooting order

Set print preview to 100%; lock paper size and orientation. Reset margin options to default and see if the issue reproduces. Decide whether on-screen preview or saved PDF is your source of truth, and note whether the gap is breaks, margins, or horizontal overflow. Still broken? Inspect @media print and whether flex/grid behaves differently in print. If tables or code split badly, switch to print-oriented break settings or tool controls. Compare another browser to detect engine-specific issues. If stuck, isolate the smallest table/code/image sample that reproduces the bug. Before wide send, open the PDF on another machine; for color-critical work use grayscale preview for contrast; verify links and QR codes on paper.

FAQ

Chrome and Firefox produce different PDFs

They use different print engines. For consistent team output, standardize on Google Chrome and document the Save-as-PDF steps in your README.

Syntax highlight background colors don't appear in PDF

Turn on "Background graphics" (or "Print background graphics") in the print dialog. In Chrome this is under More settings.

The text looks smaller in the PDF than in the preview

Check that browser zoom is at 100% and that the print dialog does not have a "Fit to page" or "Scale" option active.

Only one specific page looks wrong

Look for an unusually long line, large image, or wide table near that page. For page-break positioning issues, use drag page breaks in preview.

Takeaway

Anchor debugging on pagination, margins, horizontal width, and screen vs print CSS—and tune Markdown plus export settings together. If the same problems repeat, share one layout preset across the team so everyone's exports stay consistent.

Check your layout in the PDF preview