@Page Rule & Page Styling Basics

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.