CSS was created for styling and formatting "continuous" media, such as scrolling web pages. In comparison, "paged" media have page breaks that split up the HTML document. Examples include PDFs, books, catalogs, and presentations.
CSS Paged Media is a set of specifications that describe how CSS stylesheets should be used to style pages. This includes the CSS Paged Media Module and the CSS Generated Content for Paged Media Module.
The DocRaptor HTML to PDF API was created specifically for crafting PDF documents using CSS Paged Media. This guide will walk through those specifications and show you how they're used in creating paged media.
The CSS Paged Media Module provides tools to control the layout and appearance of content across individual pages, enabling features like page breaks, page regions, styling discrete pages, and more, including:
The @page rule defines a page box and is the basic element of paged media. Use it to define a page box size, orientation, and margins. It is the starting point for the page model.
The @page rule becomes even more powerful when paired with pseudo-class page selectors. Styles can apply to discrete pages, such as left page, right page, first page, or title page.
Content can be replicated across pages within specifc page margin boxes. They are ideal for inserting elements into like page header, page footer, page number, watermark, or any other content that needs to recur across all pages.
Counters automatically number pages in a printed or paginated document. A page count is especially necessary when working with dynamically generated content of unknown length. The counter()> function can also be used to count chapters and create references.
Page breaks obviously define when pages should break. You can use CSS to tell the renderer to break or not to break before, inside, or after particular elements. For example, you'll want to avoid a break after a chapter title (that would be awkward!) and avoid breaks inside a table. But you'll likely want to break after the end of a chapter.
Named pages let you apply distinct styles to different pages or sets of pages within a document. Named pages are handy when you want to style certain pages differently from others, like introductory pages, chapters, sections, or indices.
Printer's marks to assist with print production processes, such as crop marks (where to trim excess paper) and registration marks (for aligning different color plates).
While the CSS Paged Media Module defines the basics of the page model, the CSS Generated Content for Paged Media Module focuses on generating and manipulating the actual content of paged documents. It enables dynamic elements such as running headers, footers, footnotes, page numbers, cross-references, and more:
Running elements take content from the main flow of a document and display it in a specific page margin box across multiple pages. They're the easiest way to create headers and footers, and watermarks.
Footnotes also insert content into a page margin box, typically at the bottom of a page, though the footnote margin box can also be moved to create sidenotes. A footnote counter can be styled with numbers, asterisks, letters, or even binary numbers!
Much like regular CSS floats (float: left or float: right), page floats allow content to be floated to specific areas on the current or subsequent pages, except you can float content to the top or bottom (!!!) of a page or column. You can even defer it to appear at the top of the next page or column if it would be floated next to another floated element. (The page float specifications have recently moved into a separate CSS module)
Cross-references are dynamic links within a document that point to other parts of the same document, typically something like "See Figure 3 on page 12". This CSS functionality is critical when dealing with dynamic content of unknown length.
Named strings duplicate text content and then reuse that content elsewhere, typically in page margin boxes. They're handy for creating running headers or footers that display the title of the current chapter or section.
Leaders define a character (usually a period) used to fill the space in a line, often between a section title and a page number in tables of contents or indexes.
Bookmarks are hierarchical links that appear in the Bookmarks panel of a PDF reader. They provide an interactive table of contents that allows users to quickly jump to specific sections or destinations within a PDF document.
No. Unfortunately, both the CSS Paged Media and CSS Generated Content specifications have been stuck in W3C draft status and have been barely implemented by browsers. Google Chrome supports page size and orientation, page breaks, and page counters; but not margin boxes or named pages. Firefox is similar but even lacks support for page size and orientation.
None of the browsers currently implement any of the Generated Content module features. Because of this, it can be challenging to craft complex or dynamically generated PDFs with open-source HTML to PDF libraries based on Headless Chromium and Puppeteer.
Thankfully, DocRaptor and our PDF generator, Prince, offer comprehensive support for the CSS Paged Media and CSS Generated Content modules. Prince has even gone beyond these specifications and created custom CSS properties and JavaScript for Paged Media.
Additionally, two open-source projects focus on CSS Paged Media support. pagedjs is a collection of paged media polyfills, intended for use with browsers. WeasyPrint is a Python HTML to PDF converter. Neither of these tools provides the same level of CSS Paged Media support and flexibility as DocRaptor, but they get much closer than browsers and other open-source libraries.
CSS Paged Media functionality is critical to creating high-quality HTML to PDF conversions. Without CSS Paged Media's concept of an actual "page" with repeating elements and dynamic references, many PDF documents would be impossible to create.
The power of CSS Paged Meda is why we built DocRaptor way back in 2010, and our exclusive access to the Prince PDF Generator is a big reason why we still believe DocRaptor is the best HTML to PDF API (along with our 99.99% uptime guarantee and SOC2/HIPAA compliance, of course).
We've created a brief guide to creating printed documents below, but if you have any questions about CSS paged media, our support team would be happy to help at support@docraptor.com!
When combined, the abovementioned CSS properties and techniques offer powerful tools for creating printed pages. Our documentation, free PDF templates, and sample documents all provide detailed examples, but here's a step-by-step overview of the process:
While not necessary if your document is solely for use in an HTML to PDF generator, the first step for dual-use HTML documents is to specify which CSS stylesheets should be used while printing.
You can define print styles in a separate stylesheet and link it using the media="print" attribute, or define them within the same stylesheet using a media query.
<link rel="stylesheet" href="print.css" media="print">@media print { /* Print styles go here */ }Use the @page rule to define basic properties like page margin, page size, and page orientation:
@page {
size: A4 landscape;
margin: 1cm;
}Avoid breaking content awkwardly across pages using properties like page-break-before, page-break-after, and page-break-inside:
h1, h2, h3, h4, h5, h6 {
page-break-after: avoid;
}
table {
page-break-inside: avoid;
}If you're working with paged media processors such as DocRaptor or WeasyPrint, you can add page numbers and other generated content within page margin boxes through CSS.
@page {
@bottom-center {
content: counter(page) " of " counter(pages);
}
}Though not part of the paged media CSS specifications, Prince and DocRaptor extended CSS support for printing double-sided documents with a duplex property:
@prince-pdf {
-prince-pdf-duplex: duplex-flip-long-edge;
}DocRaptor has documentation on many other paged media and related CSS functionality, including: