path: root/docs/modules/theme/pages/running-content.adoc

= Running Content Category Keys
:navtitle: Running Content
:source-language: yaml
:conum-guard-yaml: #

The `header`, `footer`, and `running-content` category keys control the arrangement and style of running header and footer 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.

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.

[#header]
== header

The `header` category key accepts the keys listed in the following table.

IMPORTANT: If you don't specify a `height` for either the `header` or `footer` key, it effectively disables the content at that periphery.

[cols="3,4,6a"]
|===
|Key |Value Type |Example

|<<background-color,background-color>>
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
header:
  background-color: #eeeeee

|background-image
|image macro +
(default: _not set_)
|[source]
header:
  background-image: image:running-content.svg[fit=contain]

|border-color
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
header:
  border-color: #dddddd

|border-style
|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
(default: `solid`)
|[source]
header:
  border-style: dashed

|border-width
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[ends,sides\]] +
(default: `$base-border-width`)
|[source]
header:
  border-width: 0.25

|column-rule-color
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
header:
  column-rule-color: #CCCCCC

|column-rule-spacing
|xref:measurement-units.adoc[Measurement] +
(default: `0`)
|[source]
header:
  column-rule-spacing: 5

|column-rule-style
|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
(default: `solid`)
|[source]
header:
  column-rule-style: dashed

|column-rule-width
|xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
header:
  column-rule-width: 0.25

|<<columns,columns>>
|Column specs triple +
(default: _not set_)
|[source]
header:
  columns: <50% =0% <50%

|content-margin
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
(default: `[0, inherit]`)
|[source]
header:
  content-margin: 0

|font-color
|xref:color.adoc[Color] +
(default: _inherit_)
|[source]
header:
  font-color: #333333

|font-family
|xref:font-support.adoc[Font family name] +
(default: _inherit_)
|[source]
header:
  font-family: Noto Serif

|font-kerning
|`normal` {vbar} `none` +
(default: _inherit_)
|[source]
header:
  font-kerning: none

|font-size
|xref:language.adoc#values[Number] +
(default: _inherit_)
|[source]
header:
  font-size: 9

|font-style
|xref:text.adoc#font-style[Font style] +
(default: _inherit_)
|[source]
header:
  font-style: italic

|<<height,height>>
|xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
header:
  height: 0.75in

|image-vertical-align
|`top` {vbar} `middle` {vbar} `bottom` {vbar} xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
header:
  image-vertical-align: 4

|line-height
|xref:language.adoc#values[Number] +
(default: `$base-line-height`)
|[source]
header:
  line-height: 1.2

|margin
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom(n/a),left\]] +
(default: [`0`, `inherit`])
|[source]
header:
  margin: 0

|<<padding,padding>>
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
(default: `0`)
|[source]
header:
  padding: [0, 3, 0, 3]

|<<levels,sectlevels>>
|Integer +
(default: `2`)
|[source]
header:
  sectlevels: 3

|text-transform
|xref:text.adoc#transform[Text transform] +
(default: `none`)
|[source]
header:
  text-transform: uppercase

|title-style
|`document` {vbar} `toc` {vbar} `basic` +
(default: `document`)
|[source]
header:
  title-style: toc

|vertical-align
|`top` {vbar} `middle` {vbar} `bottom` {vbar} [`top` {vbar} `middle` {vbar} `bottom`, xref:measurement-units.adoc[Measurement]] +
(default: `middle`)
|[source]
header:
  vertical-align: middle

|<<columns,<side>-columns>>
|Column specs triple +
(default: _not set_)
|[source]
header:
  recto:
    columns: <25% =50% >25%

|<<side,<side>-content-margin>>
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
(default: _inherit_)
|[source]
header:
  recto:
    content-margin: [0, 0, 0, inherit]

|<<side,<side>-margin>>
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom(n/a),left\]] +
(default: _inherit_)
|[source]
header:
  recto:
    margin: [0, 0, 0, inherit]

|<<side,<side>-padding>>
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
(default: _inherit_)
|[source]
header:
  recto:
    padding: [0, 3, 0, 3]

|<<position,<side>-<position>-content>>
|xref:quoted-string.adoc[Quoted string] +
(default: `'\{page-number}'`)
|[source]
header:
  recto:
    left:
      content: '{page-number}'
|===

[#footer]
== footer

The `footer` category key accepts the keys listed in the following table.

IMPORTANT: If you don't specify a `height` for either the `header` or `footer` key, it effectively disables the content at that periphery.

[cols="3,4,6a"]
|===
|Key |Value Type |Example

|<<background-color,background-color>>
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
footer:
  background-color: #eeeeee

|background-image
|image macro +
(default: _not set_)
|[source]
footer:
  background-image: image:running-content.svg[fit=contain]

|border-color
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
footer:
  border-color: #dddddd

|border-style
|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
(default: `solid`)
|[source]
footer:
  border-style: dashed

|border-width
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[ends,sides\]] +
(default: `$base-border-width`)
|[source]
footer:
  border-width: 0.25

|column-rule-color
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
footer:
  column-rule-color: #CCCCCC

|column-rule-spacing
|xref:measurement-units.adoc[Measurement] +
(default: `0`)
|[source]
footer:
  column-rule-spacing: 5

|column-rule-style
|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
(default: `solid`)
|[source]
footer:
  column-rule-style: dashed

// TODO Since column-rule-style follows the pattern of border-style, does that mean column-rule-width follows the pattern of border-width?
|column-rule-width
|xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
footer:
  column-rule-width: 0.25

|<<columns,columns>>
|Column specs triple +
(default: _not set_)
|[source]
footer:
  columns: <50% =0% <50%

|content-margin
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
(default: [`0`, `inherit`])
|[source]
footer:
  content-margin: 0

|font-color
|xref:color.adoc[Color] +
(default: _inherit_)
|[source]
footer:
  font-color: #333333

|font-family
|xref:font-support.adoc[Font family name] +
(default: _inherit_)
|[source]
footer:
  font-family: Noto Serif

|font-kerning
|`normal` {vbar} `none` +
(default: _inherit_)
|[source]
footer:
  font-kerning: none

|font-size
|xref:language.adoc#values[Number] +
(default: _inherit_)
|[source]
footer:
  font-size: 9

|font-style
|xref:text.adoc#font-style[Font style] +
(default: _inherit_)
|[source]
footer:
  font-style: italic

|<<height,height>>
|xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
footer:
  height: 0.75in

|image-vertical-align
|`top` {vbar} `middle` {vbar} `bottom` {vbar} xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
footer:
  image-vertical-align: 4

|line-height
|xref:language.adoc#values[Number] +
(default: `$base-line-height`)
|[source]
footer:
  line-height: 1.2

|margin
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top(n/a),right,bottom,left\]] +
(default: `[0, inherit]`)
|[source]
footer:
  margin: 0

|<<padding,padding>>
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
(default: `0`)
|[source]
footer:
  padding: [0, 3, 0, 3]

|<<levels,sectlevels>>
|Integer +
(default: `2`)
|[source]
footer:
  sectlevels: 3

|text-transform
|xref:text.adoc#transform[Text transform] +
(default: `none`)
|[source]
footer:
  text-transform: uppercase

|title-style
|`document` {vbar} `toc` {vbar} `basic` +
(default: `document`)
|[source]
footer:
  title-style: toc

|vertical-align
|`top` {vbar} `middle` {vbar} `bottom` {vbar} [top {vbar} middle {vbar} bottom, xref:measurement-units.adoc[Measurement]] +
(default: `middle`)
|[source]
footer:
  vertical-align: top

|<<columns,<side>-columns>>
|Column specs triple +
(default: _not set_)
|[source]
footer:
  verso:
    columns: <50% =0% <50%

|<<side,<side>-content-margin>>
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
(default: _inherit_)
|[source]
footer:
  verso:
    content-margin: [0, inherit, 0, 0]

|<<side,<side>-margin>>
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top (n/a),right,bottom,left\]] +
(default: [`0`, `inherit`])
|[source]
footer:
  verso:
    margin: [0, inherit, 0, 0]

|<<side,<side>-padding>>
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
(default: _inherit_)
|[source]
footer:
  verso:
    padding: [0, 3, 0, 3]

|<<position,<side>-<position>-content>>
|xref:quoted-string.adoc[Quoted string] +
(default: `'\{page-number}'`)
|[source]
footer:
  verso:
    center:
      content: '{page-number}'
|===

[#background-color]
== background-color

To make the background color and border span the width of the page, set the margin to `0` and adjust the `content-margin` accordingly.

[#columns]
== columns

The `columns` key can also be defined one level up (on `header` or `footer`), in which case the setting will be inherited.
Where the page sides fall in relation to the physical or printed page number is controlled using the `pdf-folio-placement` attribute (except when `media=prepress`, which implies `physical`).
The column rules are only added if the `columns` key is specified.

TIP: Although not listed in the table above, you can control the font settings (`font-family`, `font-size`, `font-color`, `font-style`, `text-transform`) that get applied to the running content in each column position for each page side (e.g., `header-<side>-<position>-font-color`).
For example, you can set the font color used for the right-hand column on recto pages by setting `header-recto-right-font-color: 6CC644`.

[#height]
== height

If the height is not set on a periphery, the running content for that periphery is disabled.

[#padding]
== padding

Do not use negative margins.
Instead, adjust the values of the `margin` and `content-margin` keys.

[#levels]
== sectlevels

The maximum section level considered when assigning the implicit `section-title` attribute (and related) available to the running content.

[#side]
== <side>

The `<side>` in the `<side>-columns`, `<side>-margin`, `<side>-content-margin`, `<side>-padding`, and `<side>-<position>-content` keys is specified as `recto` (right-hand, odd-numbered pages) or `verso` (left-hand, even-numbered pages).

[#position]
== <position>

The `<position>` in the `<side>-<position>-content` key is specified as `left`, `center` or `right`.

[#running-content]
== running-content

The key in the `running-content` category controls on what page the running content starts.

[cols="3,4,6a"]
|===
|Key |Value Type |Example

|start-at
|`title` {vbar} `toc` {vbar} `after-toc` {vbar} `body` {vbar} Integer +
(default: `body`)
|[source]
running-content:
  start-at: toc
|===

* The `title`, `toc`, and `after-toc` values are only recognized if the title page is enabled (i.e., doctype is `book` or the `title-page` document attribute is set).
* 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 Table of Contents, the `start-at` behavior is the same as if the TOC is not enabled.
* If the value is `after-toc`, the running content will start after the TOC, no matter where it's placed in the document.
To disable 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]`).
* If the value of `start-at` is an integer, the running content will start at the specified page of the body (i.e., 1 is the first page, 2 is the second page).

//TODO Move the following sections to a page, such as add-running-content.adoc in the the theme module.

[#disable]
== Disable the header or footer

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.

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 disable this behavior, you can use the following snippet:

[source,yaml]

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


Instead of erasing the content (which is what the `~` does), you can specify content of your choosing.

[#page-number]
== Modify page number position

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

[source,yaml]

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


In the last two examples, the recto and verso both have the same content.
In this case, you can reduce the amount of configuring using a YAML reference.
For example:

[source,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.

[#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`
* `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`

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 footer:

[source,yaml]

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}*'
  verso:
    left:
      content: '*{page-number}* | {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.

[source,yaml]

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 to the header or footer

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

[source,yaml,subs=attributes+]

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.