rustedf.cloud
Menu

HTML and CSS for PDF: what works and how to check it

Published 3 min read

A page you built for a browser scrolls forever. A PDF does not: it has a fixed paper size, margins, page breaks, and a header and footer that repeat. That is why the same HTML can look right on screen and wrong on paper, and why it helps to know what a PDF renderer supports before you design for it.

This is what the rustedf.cloud renderer supports, with the pitfalls that come with it.

Layout that works

  • The CSS box model, including box-sizing, margins, and min- and max- sizes.
  • Tables with colspan and rowspan, and header rows that repeat on every page the table spans. This is what keeps a long invoice or statement readable.
  • Flexbox, and a subset of grid (grid-template-columns with lengths, fr, auto and repeat(), plus gap).
  • position: relative and absolute, z-index, multi-column text, and lists.

Paged media

This is the part most web pages never use, and it is what a document needs.

@page {
size: A4;
margin: 20mm;
@bottom-center { content: "Page " counter(page) " of " counter(pages); }
}
.signature { break-inside: avoid; }
h2 { break-after: avoid; }
  • @page sets the size, orientation and margins, and top and bottom margin boxes hold headers and footers, with the page number and the page count.
  • break-before, break-after and break-inside control where a page may end. Use break-inside: avoid so a signature block or a total is never split across two pages.
  • Headings become the outline of the PDF, and <a href> links stay clickable.

Painting

Colors, backgrounds, linear-gradient(), solid, dashed and dotted borders, border-radius, box-shadow, opacity and overflow: hidden all work. 2D transforms such as rotate() and scale() work too, but a transform only moves how an element is painted: the element keeps the space it had. 3D transforms are ignored.

Images are PNG and JPEG, either uploaded to your account (asset:<id>) or embedded as data: URLs. Simple SVG shapes (rect, circle, line) are drawn as vector shapes.

What to leave out

  • JavaScript.
  • Animations and transitions.
  • Pseudo-classes such as :hover, and anything else that only makes sense on a screen.
  • @font-face and @import. You do not need them: name a font family in your CSS and the service makes it available. See the Fonts guide.
  • Images that point to a web address. The service never fetches an address from a template.

None of these breaks the render by default. An unsupported feature is ignored and reported.

Check before it ships

Reading a list is not the same as knowing your document is clean. POST /v1/validate takes the same body as a render and builds the document, but returns a report instead of a PDF, and uses no credit.

{
"ok": false,
"pages": 1,
"diagnostics": [
{
"kind": "UnsupportedProperty",
"text": "filter",
"context": "inside <p class=\"note\">",
"count": 2
}
]
}

ok is true when there is nothing to report. Each finding names the kind of problem, the property or tag involved, where it was, and how many times it happened. Among the kinds are UnsupportedTag, UnsupportedProperty, UnsupportedSelector, ImageLoadFailed and LayoutOverflow, which flags a box taller or wider than the page.

For tests, add "strict": true to a render. The same findings then fail the request with a 422, and no credit is used. A template that stays clean in your test suite stays clean in production.

Read the full list in Supported HTML and CSS and Validating a document.

← All posts