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.

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

  1. Double margins — "Minimal/none" in the dialog plus CSS @page / body margins.
  2. Bad breaks — Through headings, or inside tables and code blocks.
  3. Backgrounds — Many browsers skip backgrounds unless explicitly allowed.
  4. Fonts — Print may substitute families, shifting line breaks.
  5. 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.

This app

Markdown to PDF adds layout settings, draggable page breaks in preview, and options to avoid splitting inside tables and code. Export once with defaults, then touch only bad pages—efficient when most sheets are fine. If external delivery is strict, also verify cover, TOC, and fonts, then read the print preview end-to-end.

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.

Related