Unlike long, scrolling websites, PDFs have pages. This difference may be more significant than initially perceived and is why our PDF engine partner, Prince, helped write the CSS Paged Media specifications. Paged Media is at the core of DocRaptor's unique capabilities.
Yes, your PDF pages follow the standard CSS box model and have margins, sizes, padding, and backgrounds. But with DocRaptor, pages also have varying orientations, page breaks, spreads (left vs. right pages), repeating elements, floats, and more. Styling your page starts with the @page
rule and expands from there!
@page Rule
The @page
rule was added by the CSS Paged Media specifications and lets you to customize your pages through simple CSS:
@page {
size: A4 landscape;
margin: 10mm;
}
By default, our pages are US-Letter sized with a portrait orientation and have 0.75
in of margin.
@page Psuedo Classes Selectors
:first Pseudo-Class
The :first
pseudo-class targets the first page of the printed document. You can use it to define specific styles that should only apply to the first page, for example, a different margin or a different header.
@page:first {
margin: 0;
}
:left and :right Pseudo-Classes
The :left
and :right
pseudo-classes target the left and right pages in a double-sided document, respectively. You can use these pseudo-classes to define specific styles for left and right pages.
@page:left {
margin-left: 3cm;
margin-right: 1cm;
}
@page:right {
margin-left: 1cm;
margin-right: 3cm;
}
Alternatively, DocRaptor also provides :recto
and :verso
selectors which are unaffected by the document's reading direction. In languages that read from left to right, :recto
identifies the right-hand page of a spread, while :verso
refers to the left-hand page. Conversely, in scripts that read from right to left, these roles are reversed: :recto
denotes the left-hand page, and :verso
designates the right-hand page of a spread.
:blank Pseudo-Class
The :blank
pseudo-class can be used to style blank pages that are generated due to forced page breaks, such the pages after a chapter or section. Often, page headers and titles are removed from these blank pages and this can be easily done with the :blank
psuedo-class:
@page:blank {
@top-center {
content: "";
}
}
Named Pages
If you want to style pages differently or use different headers or footers in a document, you can do it easily through named pages. Think of named pages as defining a page style. Each different named page can have a different style. For example, the style for a book title page normally does not have a footer with page numbers, but the style for the rest of the book's pages does have page numbers.
Named pages are defined through the page
CSS property. In the example below, we’ll create two different kinds of pages: title and chapter.
#title-page {
page: title;
}
.chapter {
page: chapter
}
Now these pages can be styled differently:
@page title {
@top {
/* no header for title pages */
content: “”;
}
}
@page chapter {
@top {
content: “This is a chapter page”;
}
}
DocRaptor will insert a page break each time the page name changes, including content that doesn’t have an explicit page name.
You can also use pseudo-classes with named pages, such as:
@page chapter:first {
@top {
content: “Chapter pages start here”;
}
}
When used in combination with page regions, named pages provide powerful flexibility for creating documents with many different styles with varying headers, footer, watermarks, page numbers, and more. This functionality is unique to the DocRaptor API and not available in open-source, Google Chromium-based libraries such as Puppeteer.