Markdown to PDF for Print, In the Browser

Markdown has no concept of a page. It is a flat stream of structural elements — headings, paragraphs, lists, code blocks — with no notion of where one sheet of paper ends and the next begins.

PDF is the opposite. It is a page-description format in which every element has an absolute position on a fixed canvas of a specific physical size.

Converting between them means inventing everything PDF requires and Markdown does not supply: page size, margins, where page breaks fall, whether a heading may sit alone at the foot of a page, how a table behaves when it is taller than the remaining space, and what appears in the running header and footer.

Those decisions are what separate a document that looks typeset from one that looks like a web page someone printed. Most converters make them badly by default, which is why Markdown-to-PDF output so often has headings stranded at page bottoms and code blocks split mid-line.

The practical route to good PDF output in a browser is not a PDF-drawing library. It is to render the Markdown to HTML and then control pagination with print CSS, letting the browser's own layout engine do the typesetting it already does well.

The @page rule defines the physical sheet:

@page {
  size: A4;
  margin: 20mm 18mm 22mm 18mm;
}

size accepts named sizes (A4, Letter) or explicit dimensions, plus portrait or landscape. Margins here are the printable margins of the sheet itself, distinct from any CSS margins inside the document body.

Pagination control comes from a small set of properties that are widely misunderstood:

```css h1, h2, h3, h4 { break-after: avoid; /* never leave a heading alone at a page foot */ break-inside: avoid; }

pre, table, figure, blockquote { break-inside: avoid; /* do not split a code block across pages */ }

p { orphans: 3; /* min lines left at the bottom of a page */ widows: 3; /* min lines carried to the next page */ } ```

break-after: avoid on headings is the single highest-impact rule in the entire stylesheet. Without it, roughly one heading in every few pages ends up stranded, and nothing else about the document matters as much to how professional it reads.

orphans and widows are typographic terms worth getting right: an orphan is a lone first line left at the bottom of a page; a widow is a lone last line pushed to the top of the next. Both look like errors to a reader even when they cannot name why.

Academic and corporate documents need page numbers, and CSS provides them through @page margin boxes and the built-in page counter:

@page {
  @bottom-center {
    content: counter(page) " of " counter(pages);
    font-size: 9pt;
    color: #555;
  }
  @top-right {
    content: "Quarterly Review — Confidential";
    font-size: 8pt;
  }
}

Support for margin boxes varies between browser print engines and dedicated renderers, and this is the main area where browser printing falls short of a typesetting tool. Where margin boxes are unavailable, a fixed-position element repeated by the print engine is the usual workaround.

Two further refinements matter for formal documents:

Different first page. Title pages usually omit the running header. @page :first targets it specifically, as do :left and :right for duplex printing with mirrored margins.

Section-aware breaks. break-before: page on top-level headings starts each chapter on a fresh sheet, which is the convention for reports and theses:

h1 { break-before: page; }
h1:first-of-type { break-before: avoid; }

The second rule prevents a blank opening page, which is the bug that always accompanies the first.

Screen typography and print typography have different constraints, and carrying screen values onto paper is what makes a printed page look wrong in a way readers notice but cannot articulate.

Use physical units. Set type in pt or mm for print, not px. A pixel has no fixed physical size; a point is exactly 1/72 inch. Body text between 10pt and 12pt is the readable range on paper — noticeably smaller than the 16px screen default, because reading distance and resolution are both different.

Measure matters more on paper. A line length of 65–75 characters is the comfortable range. An A4 page with narrow margins and 11pt type produces lines well over 100 characters, which is tiring to read. Generous margins are not wasted space; they are what makes the measure correct.

Increase leading slightly. Print benefits from line-height around 1.45–1.6 for body text.

Serif for body, still. For long-form printed text, a serif face remains easier to read at small sizes on paper, where the rendering is high-resolution and stroke contrast survives.

Make links useful on paper. A hyperlink is meaningless in print unless its destination is visible. Print stylesheets conventionally expose it:

@media print {
  a[href^="http"]::after {
    content: " (" attr(href) ")";
    font-size: 85%;
    word-break: break-all;
  }
}

The documents people convert from Markdown are rarely public. They are theses before submission, internal reports, board papers, contracts in draft, research under embargo.

Uploading such a document to a conversion service transmits the full text to a third party. Unlike an image, a document is immediately indexable and searchable by whoever receives it, and a draft under embargo loses its embargo the moment it is transmitted.

Because the browser already contains the layout engine, the conversion needs no server at all. The Markdown is parsed to HTML in the page, print CSS is applied, and the browser's own print pipeline produces the PDF. The OpenTools Markdown to PDF tool works this way.

Two practical notes for anyone relying on this route:

Fonts must be available locally or embedded. A PDF generated from a page referencing a web font that failed to load will silently substitute a fallback, and the document you send is not the document you previewed. Check the output, not the preview.

Print backgrounds are off by default. Browsers omit background colours and images when printing unless explicitly enabled. Code blocks with a tinted background, callout boxes and table zebra striping all disappear. print-color-adjust: exact requests that they be kept:

pre, .callout, tbody tr:nth-child(even) {
  print-color-adjust: exact;
  -webkit-print-color-adjust: exact;
}