Control page breaks and page size when converting Markdown to PDF

A practical guide · about 4 min read

Markdown has no concept of a page — it's just one continuous document. PDF, on the other hand, is all pages. So when you convert, the tool has to decide where one page ends and the next begins, and sometimes it picks a spot you don't love: a heading stranded at the very bottom, or a table split down the middle. This guide covers how to nudge those breaks and how to pick the right page size.

First: pick the right page size

Before worrying about breaks, set the page size to match your audience:

A4 (210 × 297 mm) — the standard almost everywhere outside North America.
Letter (8.5 × 11 in) — the US and Canada.

Getting this wrong is a common cause of “it looked fine on screen but printed with a weird margin.” In the converter you choose A4 or Letter before downloading. If you'll print the document, match the paper in the printer; if it's only ever read on screen, A4 is the safe default.

Forcing a page break before a section

Sometimes you want a section — “Appendix”, “Part 2”, the next chapter — to always start on a fresh page. The cleanest, most portable way is a tiny bit of inline HTML in your Markdown, since Markdown allows raw HTML:

Some final text on this page.

<div style="page-break-before: always"></div>

## Appendix
This heading now starts a new page.

The browser's print engine respects page-break-before: always (and the newer break-before: page), so the PDF starts a new page right there. This works in most browser-based and HTML-rendering converters.

Stopping a heading from being orphaned

An “orphaned” heading is one that lands at the very bottom of a page while the text it introduces flows onto the next. It looks broken. A few ways to avoid it:

Insert a manual break before the heading using the snippet above, so it deliberately starts the next page.
Trim a few lines earlier in the document so everything shifts up and the heading no longer falls at the boundary.
Adjust the margins (below) — even a small change moves where breaks fall.

Keeping a table or code block together

A table or a fenced code block split across two pages is hard to read. If a converter exposes CSS, the property that helps is:

table, pre { break-inside: avoid; }

This asks the engine to keep the whole block on one page if it fits. It can't work miracles — a table taller than a full page has to break somewhere — but for normal-sized blocks it prevents the ugly mid-table split. If your tables are the main concern, the tables and code guide goes deeper.

Margins and the print dialog

When you save as PDF from the browser, the print dialog has a few settings worth a glance:

Margins — “Default” is fine for most documents; “Minimum” fits more on each page if you're trying to save a page.
Scale — leave at 100% unless you're deliberately shrinking to fit.
Background graphics — turn this on if your style has shaded code blocks or table headers, otherwise they print white.

In short

Set the page size first (A4 or Letter), use a one-line page-break-before div to force section breaks, and lean on break-inside: avoid to keep tables and code intact. Those three controls handle almost every “why did it break there” problem when going from Markdown to PDF.