= Add Running Content
:conum-guard-yaml: #

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 <<start-at,specify on which page the header and footer start>>.

CAUTION: 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 xref:running-content.adoc[] for the complete list of keys you can use to customize your running content.

[#columns]
== Columns

By default, the header and footer running content is partitioned into three columns that all span the full content width of the running content box.
These columns are mapped to the keys `left`, `center`, and `right` in the theme.
The content is aligned within the column based on its position (e.g., content in the right column is aligned to the right).
In order for there to be content in the column, that content must be defined in the theme.

You can control the number and width of columns in the running content using the `columns` key on the respective running content periphery (`header` or `footer`), which can be overridden by the `columns` key on the side for that periphery (`recto` or `verso`).

The running content supports maximum of 3 columns.
The columns are defined using colspecs.
A colspec defines the width of each column with an optional alignment.

The width is represented in percentage of available space (the space from the left margin to the right margin).
The widths do not have to add up to 100%, meaning each column can use whatever portion of available space it wants (absolute lateral positioning), though a total of 100% is recommended.

The alignment is expressed as a symbol, `<`, `=`, `>` to represent left, center, and right, respectively.
The alignment must precede the width.
If the alignment isn't specfied, it defaults to `<`.

Let's look at an example of a colspec:

[,yaml]
----
footer:
  columns: =100%
----

This colspec defines a single column which uses all available space and centers its content.
The column is mapped to the `center` key for defining content and other properties.
Using this column value causes the `left` and `right` keys to be ignored.

The colspecs are separated using a comma or space.
The position (and thus name) of the column is inferred by its position in the list.
The positions per number of columns are mapped as follows:

1:: center
2:: left and right
3:: left, center, and right

Let's look at example of a 3-column configuration:

[,yaml]
....
footer:
  columns: <25% =50% >25%
....

This colspec defines three columns.
The content is aligned to the left for the left column, to the center for the center column, and to the right for the right column.
The left and right columns occupy 25% of the available space and flank the center column that occupies 50%.
To align the right column to the left, replace the colspec with <25%.

Now let's look at example of a 2-column configuration.

[,yaml]
....
footer:
  columns: <25% >25%
....

This colspec defines two columns.
The left column is aligned to the left and the right column is aligned to the right.
Each column uses 25% of the available space.

To configure 0 columns, assign and empty string to the `columns` key.

[#start-at]
== 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.

[,yaml]
----
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`.

[[page]]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.

TIP: 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]`).

[#page-number]
== 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.

[,yaml]
----
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.

[,yaml]
----
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 xref:page-numbers.adoc[].

[#attribute-references]
== 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 `+&#169;+`, hexadecimal character references like `+&#x20ac;+`, 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:

[,yaml]
----
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 `{sp}+` to the end of the line in normal AsciiDoc fashion.

[,yaml]
----
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}
----

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

[,yaml,subs=attributes+]
----
extends: default
header:
  height: 0.75in
  image-vertical-align: 2 {conum-guard-yaml} <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.

CAUTION: 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]
== 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:

[,yaml]
----
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.

[,asciidoc]
----
= 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.

[,asciidoc]
----
= Document Title
:doctype: book
:toc: macro

[dedication]
== Dedication

Credit where credit is due.

[%noheader%nofooter]
toc::[]

== First Chapter
----
