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 top-level 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 last page of the TOC, no matter where the TOC is placed in the document. If media=prepress, this keyword refers to the next recto page after the last page of the TOC. The after-toc value is primarily intended to be used with the book doctype, though it can be used with the article doctype if the title page is enabled. If the TOC is not enabled, or the title page for an article is not enabled, this value reverts to body.
body: This is the default value. The running content starts on the first page of the document body. If the TOC is enabled in its default location, the first page of the document body is the next recto page after the TOC when media=prepress or the page that immediately follows the TOC otherwise.
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, no matter where the TOC is placed in the document. The toc value is primarily intended to be used with the book doctype, though it can be used with the article doctype if the title page is enabled. If the TOC is not enabled, or the title page for an article is not enabled, this value reverts to body.
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). Refer to the body value for an explanation of where the body starts. For a prepress book (doctype=book and media=prepress), the running content starts on the empty verso page before the body if the value is 0. An integer value is recognized by all doctypes and 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
part-numeral (only set on part title page when part numbering is enabled)
chapter-title
chapter-numeral (only set on chapter title page when section numbering is enabled)
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 title-style 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:

extends: default
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.

extends: default
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 images 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 entire value of the content for a given position, it acts like a background image. That means you can use the fit attribute scale it relative to the column’s box. The position and align attributes on the macro aren’t currently recognized. Rather, the horizontal position is controlled by the alignment of the column and the vertical position is controlled by the image-vertical-align key on the periphery.

If the image macro is adjacent to other text, the image behaves just like any other inline image. In this case, you can only adjust the width of the image using the width attribute (e.g., width=16) or the fit=line attribute.

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

extends: default
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.

= Document Title
:noheader:
:nofooter:

No running content in this document.

If you want to disable the header and footer on pages in the TOC that were added using the toc macro, you can do so by setting the noheader and/or nofooter options on the toc macro.

= Document Title
:doctype: book
:toc: macro

[dedication]
== Dedication

Credit where credit is due.

[%noheader%nofooter]
toc::[]

== First Chapter