Configure the Page Numbers

The pagenums document attribute is set by default when Asciidoctor PDF runs. In turn, pagenums implicitly sets the page-number attribute in running content. To complement the current page number, the virtual page count is assigned to the page-count 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.

When using a theme that’s configured to show page numbers in the running content (such as the footer), you can quickly hide the page numbers by unsetting the pagenums document attribute in the document header (or via the API).

In doing so, it will also hide all other text on the same line of the column in the running content. Therefore, a more formal way of hiding page numbers is to configure the running content to not include them.

Here’s an example of a theme that extends the default them to show legal text instead of the page number.

Notice that there is no reference to {page-number}, hence why no page number will appear. You can find more details in the section Modify page number position.

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.

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

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.

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.

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).

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.

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, you can add the page number to the running content by using the {page-number} attribute reference in the content key.

You can also reference the virtual page count (i.e, the final page number) using the page-count attribute.

You can use this same content value to add page numbering to the running content of any custom theme.