Configure the Page Numbers

Asciidoctor PDF automatically keeps track of page numbers. These page numbers are available as metadata and determine the folio placement of each page.

Default numbering and folio placement

The pagenums document attribute is set by default when Asciidoctor PDF runs. In turn, pagenums implicitly sets the page-number attribute.

The converter assigns the page number 1 to the first body page of the document and then increments the page number for each page thereafter. All front matter pages, including the cover page, title page, and TOC pages, that precede the first body page when the doctype is book or when the title-page attribute is set are numbered using roman numerals (e.g., i, ii, iii). These computed page numbers can differ from the physical page numbers, therefore, we refer to them as virtual page numbers. The default theme shows the virtual page number in the footer of all body pages.

The folio placement — whether the page is recto or verso — is derived from the virtual page number. When using the built-in themes with the default page numbering and running content settings, odd page numbers (e.g., 1, 3, 5) designate recto pages and even page numbers (e.g., 2, 4, 6) designate verso pages. The page number is displayed in the right corner of the footer on recto pages and in the left corner of the footer on verso pages.

You can change where the virtual page numbering starts, how the numbers are styled and positioned, what page the numbers start being displayed on, and adjust the folio placement using a combination of theme keys and AsciiDoc document attributes.

Starting integer page numbering

The theme can specify the page where the integer (1-based) page numbering should begin using the start-at key. The start-at key is set on the page-numbering category in the theme.

page:
  numbering:
    start-at: toc

The start-at key accepts the following keywords or an integer:

after-toc: The integer page numbering starts after the TOC, no matter where the TOC is placed in the document. The after-toc value is only recognized if the title page is implicitly or explicitly enabled.
body: This is the default value. The integer page numbering starts on the first page of the document body, which is typically the first page after the TOC if the TOC is in its default location.
cover: The integer page numbering starts on the front cover page of the document. The cover value is only recognized if the document has a front cover page (i.e., front-cover-image).
title: The integer page numbering starts on the title page. The title value is only recognized if the title page is implicitly or explicitly enabled.
toc: The integer page numbering starts on the first page of the TOC. The toc value only applies if the TOC is in the default location (before the first page of the body). If the value is toc, and the toc macro is used to position the TOC, the start-at behavior is the same as if the TOC is not enabled. The toc value is only recognized if the title page is implicitly or explicitly enabled.
Integer: The page numbering starts at the specified page of the body (i.e., 1 is the first body page, 2 is the second body page). An integer value is recognized by all doctypes and the title page doesn’t need to be enabled.

Let’s start the integer page number on the title page of a document. This requires that a title page be created when the PDF is generated, therefore, make sure you’ve set the doctype to book or set the title-page document attribute. Then, under the page-numbering category in your theme, set start-at and assign it the value title.

Start page numbering on title page

page:
  numbering:
    start-at: title

The title page will be assigned the virtual page number 1 and the page number will increment for each page thereafter. Alternately, the theme can specify an offset from the first body page where the page numbering should begin when an integer is assigned to start-at.

Offset page numbering from first body page

page:
  numbering:
    start-at: 3

In the example above, page-numbering-start-at: 3 tells the converter to assign the virtual page number 1 to the third page of the body. Any page that precedes that page will be numbered using roman numerals.

Changing the page on which the integer page numbering begins can alter the folio placement. To correct for this, or to change the folio placement in general, you can use the pdf-folio-placement document attribute.

For instance, to base the folio placement on physical page numbers, set the value of this attribute to physical (e.g., pdf-folio-placement=physical). To invert the recto and verso pages, add the -inverted qualifier to the value (e.g., pdf-folio-placement=physical-inverted).

Styling the page numbers

The built-in themes show the virtual page number in the footer of all body pages. Assuming the default page numbering and running content settings are in use, the page number if placed near the right corner of the footer of recto body pages and near the left corner of the footer of verso body pages. You can change where the page numbers are positioned in the running content and how they’re styled by configuring the header and footer category keys. See Modify page number position for an example of how you can replace the alternating page numbers with a centered page number.

Displaying the page numbers

To adjust on what page the page numbers begin to be displayed on, you need to change the page on which the running content starts. This is controlled by the running-content-start-at key. For example, to start the running content on the title page, assuming the title page is enabled, set running-content-start-at: title in your theme file. To learn more about customizing the running content, see Add Running Content.

If you’re not extending one of the built-in themes and starting with a blank theme, you can add the page number to the running content by using the {page-number} attribute reference in the content key.

Add page number to footer in blank theme

footer:
  recto:
    right:
      content: '\{page-number}'