Page size

Page size can be specified using the size property in length units or by a page size keyword (see Page Size Keywords for a list) optionally combined with the portrait or landscape keyword.

/* Use A4 paper */
@page { size: A4 }

/* Use A4 paper in landscape orientation */
@page { size: A4 landscape }

/* These two custom sizes are equivalent */
@page { size: 30cm 40cm }
@page { size: 40cm 30cm landscape }

/* Use square paper, this sets width and height */
@page { size: 30cm }

Sometimes it can be useful to specify the page dimensions in pixels, for example when creating presentation slides. (see Presentation slides).

@page { size: 1280px 960px }

Page style

Pages, like other block level elements, follow the CSS box model introduced in CSS Box Model. Their padding , border , margins and background can be styled within @page rules.

@page {
    margin: 2cm;
}

Prince also supports the margin-outside and margin-inside properties. These allow you to specify different margins for the inside and outside edges of paper as it is bound into a book. For example it may be necessary to have a larger inside margin (sometimes called a gutter) so that after some of the margin is used by the binding, the remaining margins are even.

@page {
    margin: 2cm;
    margin-inside: 3cm;
}

This is used in Fancy headers

Trimming marks

Furniture catalogue example

The furniture catalogue with bleed and trim areas for printing and cropping. Download the PDF or the HTML and CSS.

When typesetting a magazine or flyer it can be useful to print right to the edge of the paper. However most printers will refuse do do this. It is better to print on larger stock and then crop the paper to the correct size. If you use the marks property, Prince will create bleed and trim areas around your content (and the declared page size). This can be seen in the catalogue example, adapted from the Catalogue sample in the Prince samples repository.

@page{
    size: 8.5in 10.5in;
    margin: 0;
    background: url("images/CatalogueCover.jpg");
    background-position: center;
    background-size: 104%;
    background-repeat: no-repeat;
    marks: crop cross;
    prince-bleed: 0.25in;
    prince-trim: 0.25in;
}

This example uses some of the properties that we introduced above, plus three new ones: marks, prince-bleed and prince-trim. These options enable crop and cross marks and specify bleed and trim areas. Note that size of the content does not change when we add these options, the page is still 8.5in by 10.5in as specified by the size property. Instead 0.25in of bleed area and 0.25in of trim area has been added to each edge (1in total). Therefore we will need to print on 9.5in by 11.5in paper. Prince will print solid background colours and repeating pictures into the bleed area - we set the background size to 104% so that it would print into the bleed area.

Prince also allows the placement, length and width of the crop marks to be specified respectively with the prince-mark-offset, prince-mark-length and prince-mark-width properties.

Page regions

Page regions

A page with content in some of its page regions.

Most content appears inside the page box of one or more pages. Surrounding the page box, within the margin area, but also overlaying the page, are the page regions. Figure Page regions shows the positions of some page regions. In this figure the @page background is a grey and body's background is white. The first four page regions: @top, @bottom, @left and @right are easy to understand and are shown in yellow and red. Each of these page regions has a synonym ending in -center, for instance @top-center is the same as @top. You can place content in a page region with the content property. For example you can print the current page number at the bottom of each page (see Generated Content):

@page {
    @bottom {
        content: counter(page)
    }
}

Novel title page example and Textbook page numbers example show examples of headers and footers.

Several other page regions can also be used. All the page regions are shown in Page regions. Prince will try to create page regions of the correct sizes, If you need to create boxes of specific sizes you may need to use only a single box (eg: @top) and use the content property to place elements with specific sizes in it. Note that in the Figure Page regions Prince leaves space for @top-right and @left-bottom boxes because their counterparts (@top-left and @left-top respectively) have been defined. This keeps the @top and @left centered along the top and side of the page respectively.

The page region @prince-overlay is a special region, overlaying all of the page box. A typical use is for creating watermarks on all pages (see Watermarks).

The page region @footnotes is placed at the foot of the page box and contains the footnotes (see Footnotes).

Many CSS properties can be applied to page regions:

• All of the margin, padding, border and background properties can be used to style page regions.

• The vertical-align property can be applied to any page region to vertically align its content.

• When a page region contains generated content, many inline style properties such as color and font can be applied to style the generated content.

Generated content in page regions

We have already shown an example of using the page counter to print the page number at the bottom of each page, this is one example of generated content. The page counter is predefined and starts at 1; it increments automatically for each new page. (Note that the page counter cannot be incremented manually using the counter-increment property.

The page counter can be reset using the counter-reset property at any block-level element within a non-floating element in the normal flow. This is useful for restarting page numbering at a new section of the document.

Restarting page numbering

<body>
    <div class="front"> cover page, etc, ... </div>
    <div class="contents">
        table of contents, ...
    </div>
    <div class="body">
    <div class="chapter"> chapter 1...</div>
    <div class="chapter"> chapter 2...</div>
    </div>
    <div class=appendix"> appendix1 </div>
    <div class=appendix"> appendix2, ... </div>
</body>

.contents {
    display: block;
    page: table-of-contents;
    counter-reset: page 1
}
@page table-of-contents {
    @top { content: "Table of Contents" }
    @bottom {
        content: counter(page, lower-alpha)
    }
}

.body {
    display: block;
    page: main;
    counter-reset: page 1
}
@page main {
    @top { content: string(chapter-title) }
    @bottom {
        content: counter(page)
    }
}

.chapter h1 { string-set: chapter-title content() }

Restarting page numbering also uses Named pages which we will explain in more detail below. We create three types of pages: table-of-contents pages, main pages, and pages without a name.

The .contents rule names the pages that it appears on as table-of-contents and resets the page counter to 1 at the start of the contents div. Then the @page rule for those pages generates a page footer that contains the current page number in lower-alpha style. This rule also sets the page header to the string "Table of Contents".

The .body rule names the pages that it appears on as main and resets the page counter to 1 at the start of main div. Then the @page rule for the main pages generates a page footer that contains the current page number in the default decimal style. This rule, together with the .chapter h1 rule, sets the page header to the title of the chapter (see Generated Content).

Pages that don't match either of these names have the default style, which does not include a page number in the footer.

In some documents, particularly those that are unbound such as office documents, it can be useful to show the total number of pages on each page. The total number of pages can be accessed using the pages counter. This is a pre-defined counter that is fixed to the total number of pages in the document.

@page {
    @bottom {
        content: "Page " counter(page) " of " counter(pages)
    }
}

This rule will generate page footers such as "Page 1 of 89".

Fancy header example

This example shows a header as might be found in a textbook. The HTML and PDF are both available. This is a small part of a larger example in our Prince samples repository.

Fancy headers

This example demonstrates a more complete headers style. It uses generated content to print page numbers, the chapter number and title and the section number and title using different styles for left and right pages. It also prints an underline under the header, See Fancy header example .

@page {
    font-family: Times, Serif;
    font-size: 11pt;
    text-align: justify;
    margin-top: 2cm;
    margin-bottom: 2cm;
    margin-inside: 3.5cm;
    margin-outside: 2.5cm;
}

@page body:left {
    @top-left {
        content: counter(page);
        vertical-align: bottom;
    }
    @top-right {
        content: "Chapter " counter(chapter) ": " string(chapter);
        vertical-align: bottom;
    }
}
@page body:right {
    @top-right {
        content: counter(page);
        vertical-align: bottom;
    }
    @top-left {
        content: counter(chapter) "." counter(section) " "
            string(section);
        vertical-align: bottom;
    }
}
@page body {
    border-top: thin black solid;
}
@page body:first {
    margin-top: 25%;
    @top-left { content: normal; }
    @top-right { content: normal; }
    border: none;
}
@page body:blank {
    @top-left { content: normal; }
    @top-right { content: normal; }
    border: none;
}
body {
    font-family: Times, Serif;
    font-size: 11pt;
    text-align: justify;
    padding: 0.5cm 0cm;
}

div.body {
    page: body;
}

div.body h1 {
    page-break-before: right;
    prince-page-group: start;
    string-set: chapter content();
    counter-increment: chapter;
    counter-reset: section;
}
div.body h1::before {
    content: "Chapter " counter(chapter) ": ";
}

div.body h2 {
    string-set: section content();
    counter-increment: section;
}
div.body h2::before {
    content: counter(chapter) "." counter(section) " ";
}

The main content area is 2.5cm from the page's edge on all sides. On the left and right this is a margin of 2.5cm and on the top and bottom it's 2cm of margin and 0.5cm of padding. This places the bottom border of the @top page region 0.5cm from the main content area, enough to avoid making it look crowded. The header text has the vertical-align: bottom property to ensure that it appears immediately above the border — the border is made to look like an underline. This example uses many properties and page selectors discussed later in this section. This is a small part of a larger example in our Prince samples repository.

Another typical usecase for generated content is when content is moved from the document to a page page region by removing an element from the normal flow and placed in a page page region. See the section Taking elements from the document for details.

Selecting pages

It is often necessary to apply styles to some pages, but not others. Either applying them to only some pages, or on every page except selected pages. CSS and Prince provide a number of page selectors for choosing which pages a rule applies to.

Novel title page example

A title page example showing use of @page:first. Download the PDF or the HTML.

In a novel it is useful to print a page number at the bottom of every page, except for some pages such as the title page. In this example the @page rule is applied to all pages. Then the @page:first rule, which is more specific, removes the footer from the first page. See Page regions and Generated Content.

<html>
<head>
<style>
@page {
    @bottom {
        content: counter(page)
    }
}
@page:first {
    margin-top: 10cm;
    @bottom {
        content: normal
    }
}
h1, h2.subtitle {
    text-align: center
}
h2.chaptertitle {
    page-break-before: always
}
</style>
</head>
<body>

<h1>The Magnificent Octopus</h1>
<h2 class="subtitle">S. Baldrick</h2>

<h2 class="chaptertitle">Chapter 1</h2>
<p>Once upon a time there lived a little saussage.</p>

</body>
</html>

In this example the @page rule specifies styles that apply to all pages: Then the @page:first rule overrides this for the first page only. It resets the content property for the footer and increases the top margin, printing the title of the novel in a reasonable place on the page (see Page style). This example also uses the page-break-before property to force a page break (see Page breaks).

Textbook page numbers example

A text book example showing use of @page:left and @page:right. Download the PDF or the HTML.

When using the :first page selector to choose the first page in each chapter (such as in Fancy headers) it may be necessary to add prince-page-group: start to the first element in each chapter (such as h1). See Page groups.

The :left and :right page selectors can be used to style left and right pages in a bound book differently. This is often used in text books to place the page number on the outside top corners of pages.

@page:left {
    @top-left { content: counter(page) }
    @top-right { content: string(book-title) }
    margin-left: 2cm;
    margin-right: 3cm;
}
@page:right {
    @top-left { content: string(chapter-title) }
    @top-right { content: counter(page) }
    margin-left: 3cm;
    margin-right: 2cm;
}

h1 { string-set: book-title content() }
h2 { string-set: chapter-title content() }

These rules also place the book title in the header of left pages, and the current chapter's title in the header of right-facing pages. The book title is copied from the text content of the h1 element while the chapter title is copied from the text content of the h2 elements (see Generated Content). They also specify wider margins in the gutter of the page spread; binders may need this extra width for a book's binding.

The first page in a document using the default left-to-right reading order is a right page. Imagine the cover or a title page of a book which appear on a right page. The first page of a right-to-left document is a left page.

By putting page-break-before: left or right at the very beginning of the document, it will not leave a blank page, but instead will change whether the document begins on a left or right facing page.

Sometimes it can be useful to select the Nth page in a document. The :nth(N) page selector can be used to do this:

@page:nth(42) {
    ...
}

Blank pages

A special case are blank pages.

As we discussed in the previous section page-break-before: right can be used to place the first page of a chapter on the right page in a spread. If the previous page is a right page then two page breaks are inserted, leaving a blank left page. However, this page will have normal @page styles applied to it, which is usually not what people want. The :blank page selector can be used to change the style of blank pages, pages skipped such as a left page before a page-break-before: right, including removing any content.

@page:left {
    @top-left {
        content: counter(page);
    }
}
@page:right {
    @top-right {
        content: counter(page);
    }
}

@page:blank {
    @top-left {
        content: normal;
    }
    @top-right {
        content: normal;
    }
}

h1 {
    page-break-before: right;
}

This example clears the generated content used on these pages. This works because :blank is more specific than either :left or :right. The :blank page selector can also be used with named pages.

@page frontmatter {
    @bottom { content: counter(page, lower-roman); }
}

@page frontmatter:blank {
    @bottom { content: normal; }
}

Note that when used with named pages, the blank page has the same name as the page following it. For example when typesetting a book with frontmatter named pages for the title page, table of contents etc, and main named pages for the main content. Will need the blank page (if one is produced) between the table of contents and the first chapter to be typeset with @page main:blank page selector. If chapter 1 also resets page numbering, then the page numbers will be reset on the first content page (a non-blank page).

It is not always best to have no content on blank pages. Sometimes otherwise blank pages are required have some content, such as a notice saying "This page sententially left blank". For example in legal documents this prevents people from mistaking a dangerous printing error for an intentionally blank page.

Controlling pagination

Prince will create page breaks automatically when new content will not fit on a page. Sometimes it is useful or necessary to control where page breaks should and should not be used. There are two ways to do this, and both are useful in different circumstances: page breaks can be added or prohibited with the Page breaks properties, and the how to control where within a paragraph a page break may occur with Widows and orphans properties.

Page breaks

The simplest case is when you want to explicitly create a page break. This is typically used at the beginning of a chapter, to start the new chapter on a new page.

h1 {
    page-break-before: always
}

page-break-before is used to force a page break immediately before an h1 element, New chapters are often started on the recto pages in text books, this is usually the right page:

h1 {
    page-break-before: right
}

Other values are auto, avoid and left.

The property page-break-after may also be used to force a page break after an element,

Presentation slides

Presentation slides example

Two overhead slides for a presentation. The slides use white on black for better contrast on most projectors, and a 4x3 aspect ratio. Download the PDF or the HTML and CSS.

It is necessary to force a page break when creating overhead slides. This can be done by placing the content for each slide in a <div class="slide"> and using page-break-before: always as shown below. This example shows other styling that may be required to create presentation slides.

@page {
    size: 1280px 960px;
    @bottom-left {
        content: "Presentation Title";
    }
    @bottom-right {
        content: counter(page);
    }
    background: black;
    color: white;
    font-family: DejaVu Sans, sans-serif;
    font-size: 16pt;
    margin: 96px;
}

@page:first {
    @bottom-left { content: normal }
    @bottom-right { content: normal }
}

div.centerpage {
    /*
     * Cause the content on these pages to begin part-way through
     * the page. This is useful for a title page.
     */
    margin-top: 33%;
}

body {
    font-size: 28pt;
    font-family: DejaVu Sans, sans-serif;
    color: white;
}

div.slide {
    page-break-before: always;
}

<div class="slide">
  <h2>Slide Title</h2>

  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
    eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
    ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
    aliquip ex ea commodo consequat. Duis aute irure dolor in
    reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
    pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
    culpa qui officia deserunt mollit anim id est laborum.
  </p>
</div>

The font-family and color properties are specified both in the @page and body rules, even though they're the same. This is required because the page regions are outside of the body and must be styled separately, likewise the content within body cannot be styled by the @page rule.

A rendered slide for this example is shown in Presentation slides example . The example has been adapted from slides (HTML+CSS) for a presentation about the Mercury programming language. This is part of our samples repository. You are encouraged to use samples from the repository and contribute your own.

So far we have discussed forcing a page break, however suppressing page breaks is also important. For example, it is poor style to have a page break between a header and the first paragraph of a section. Therefore, the default Prince stylesheet will use the page-break-after property to suppress page breaks immediately after headers:

h1, h2, h3, h4, h5, h6 {
    page-break-after: avoid
}

If a heading occurs at the bottom of a page, it may be moved to the next page to keep it with the content that follows it, usually a paragraph.

Avoiding page breaks within an element is also important. For example, it is best to avoid breaks within a figure or table. This can be done with the page-break-inside property:

.figure, table {
    page-break-inside: avoid
}

If the figure or table would have been split across two pages, it may be moved to the next page to keep it in one piece. An element longer than one page will still need to be split across multiple pages.

Note that the page-break-inside property cannot be used to create page breaks; its only valid values are auto and avoid.

These three properties can be applied to block-level elements, table rows and table row groups that occur within an in-flow element (ie. inside the normal flow of the document, not inside a float or an absolutely positioned block). Therefore the figure and table example only make sense when the figure or table is not floated.

Page breaks have similarities with column breaks, see Columns.

p {
    orphans: 2
}

p {
    widows: 2
}