Add Running Content

You can customize the arrangement and style of the running header and footer content by extending the built-in themes and using the header, footer, and running-content category keys.

Activate the running content

The running content won’t be activated unless:

the periphery (header or footer) is configured, and
the height key for the periphery is assigned a value.

By default, the built-in themes insert a footer with the page number on the right side of recto pages and the left side of verso pages if you don’t specify any running content. By extending the base or default themes, you can add content to and customize the layout of the header and footer, or disable the running content. Using the running-content key, you can also specify on which page the header and footer start.

If the height of the running content periphery is taller than the page margin, the running content will cover the main content. To avoid this problem, reduce the height of the running content periphery or make the page margin on that side larger.

See Running Content Category Keys for the complete list of keys you can use to customize your running content.

Start page

By default, the running content starts on the first page of the document body. You can specify on what page the running content starts using the start-at key. The start-at key is set on the running-content key in your theme.

running-content:
  start-at: toc

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

after-toc: The running content 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 running content 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.
title: The running content starts on the title page. The title value is only recognized if the title page is implicitly or explicitly enabled.
toc: The running content 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 running content starts on the page that matches the number assigned to start-at (i.e., 1 is the first body page, 2 is the second body page). When an integer is assigned to start-at, the title page doesn’t need to be enabled.

To turn off the running content on TOC pages inserted by the toc macro, set the noheader or nofooter options on the macro (e.g., toc::[opts=nofooter]).

Modify page number position

To replace the alternating page numbers with a centered page number, you can restrict the footer to a single column and specify the content for the center position.

extends: default
footer:
  columns: =100%
  recto:
    center:
      content: '{page-number}'
  verso:
    center:
      content: '{page-number}'

If the recto and verso keys have the same content, you can reduce the amount of configuring using a YAML reference.

extends: default
footer:
  columns: =100%
  recto: &shared_footer
    center:
      content: '{page-number}'
  verso: *shared_footer

The &shared_footer assigns an ID to the YAML subtree under the recto key and the *shared_footer outputs a copy of it under the verso key. This technique can be used throughout the theme file as it’s a core feature of YAML.

To learn more about the default page numbering and how to customize the numbering, see Configure the Page Numbers.

Attribute references

You can use any attribute defined in your AsciiDoc document (such as doctitle) in the content of the running header and footer. In addition, the following attributes are also available when defining the content keys in the footer:

page-count - the highest page number in the document (not necessarily the number of physical pages)
page-number (only set if the pagenums attribute is set on the document, which it is by default)
page-layout
document-title
document-subtitle
part-title
chapter-title
section-title
section-or-chapter-title

The value of the *-title attributes in the running content matches the text as it appears in the table of contents. You can control the style of the text stored in these attributes using the title-style key on the periphery category (header or footer) in the theme. The key accepts the values toc (as the title appears in the TOC), document (as the title appears in the document), and basic (title only, no signifier or number prefix).

If you reference an attribute which is not defined, all the text on that same line in the running content will be dropped. This feature allows you to have alternate lines that are selected when all the attribute references are satisfied. One case where this is useful is when referencing the page-number attribute. If you unset the pagenums attribute on the document, any line in the running content that makes reference to {page-number} will be dropped.

You can also use built-in AsciiDoc text replacements like (C), numeric character references like ©, hexadecimal character references like €, and inline formatting (e.g., bold, italic, monospace).

Here’s an example that shows how attributes and replacements can be used in the running content:

header:
  height: 0.75in
  line-height: 1
  recto:
    center:
      content: '(C) ACME -- v{revnumber}, {docdate}'
  verso:
    center:
      content: $header-recto-center-content
footer:
  background-image: image:running-content-bg-{page-layout}.svg[]
  height: 0.75in
  line-height: 1
  recto:
    right:
      content: '{section-or-chapter-title} | {page-number} of {page-count}'
  verso:
    left:
      content: '{page-number} of {page-count} | *{chapter-title}*'

Multi-line values

You can split the content value across multiple lines using YAML’s multiline string syntax. In this case, the single quotes around the string are not necessary. To force a hard line break in the output, add + to the end of the line in normal AsciiDoc fashion.

footer:
  height: 0.75in
  line-height: 1.2
  recto:
    right:
      content: |
        Section Title - Page Number +
        {section-or-chapter-title} - *{page-number}*
  verso:
    left:
      content: |
        Page Number - Chapter Title +
        *{page-number}* - {chapter-title}

You can use most AsciiDoc inline formatting in the values of these keys. For instance, to make the text bold, surround it in asterisks (as shown above). One exception to this rule are inline images, which are described in the next section.

Add an image

You can add an image to the running header or footer using the AsciiDoc inline image syntax. The image target is resolved relative to the value of the pdf-themesdir attribute. If the image macro is the whole value for a column position, you can use the position and fit attributes to align and scale it relative to the column box. Otherwise, the image is treated like a normal inline image, for which you can only adjust the width.

Here’s an example of how to use an image in the running header (which also applies for the footer).

header:
  height: 0.75in
  image-vertical-align: 2 (1)
  recto:
    center:
      content: image:footer-logo.png[pdfwidth=15pt]
  verso:
    center:
      content: $header-recto-center-content

1	You can use the `image-vertical-align` key to slightly nudge the image up or down.

The image must fit in the allotted space for the running header or footer. Otherwise, you’ll run into layout issues or the image may not display. You can adjust the width of the image to a fixed value using the pdfwidth attribute. Alternatively, you can use the fit attribute to set the size of the image dynamically based on the available space. Set the fit attribute to scale-down (e.g., fit=scale-down) to reduce the image size to fit in the available space or contain (i.e., fit=contain) to scale the image (up or down) to fit the available space. You should not rely on the width attribute to set the image width when converting to PDF.

Disable the header or footer

If you extend either the base or default theme, and don’t specify content for the footer, the current page number will be added to the right side on recto pages and the left side on verso pages. To turn off the default content, use the following snippet:

extends: default
footer:
  recto:
    right:
      content: ~
  verso:
    left:
      content: ~

If you define running header and footer content in your theme (including the height), you can still disable this content per document by setting the noheader and nofooter attributes in the AsciiDoc document header, respectively.