= Running Content Category Keys
:description: Reference list of the available running content, header, and footer category keys and their value types.
: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.

[#header]
== header

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

IMPORTANT: If you don't specify a `height` for the header, it effectively disables the header.
To enable the border, you must at least set the `border-width` key.
If the `border-color` key is not specified, the border color will default to `$base-border-color`.

[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
|xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] +
(default: _not set_)
|[source]
header:
  background-image: image:running-content.svg[fit=contain]

|border-color
|xref:blocks.adoc#border-color[Color] +
(default: `$base-border-color`)
|[source]
header:
  border-color: #DDDDDD

|border-style
|xref:blocks.adoc#border-style[Border style] +
(default: `solid`)
|[source]
header:
  border-style: dashed

|border-width
|xref:blocks.adoc#border-width[Measurement] {vbar} xref:blocks.adoc#border-width[Measurement[\]] +
(default: _not set_)
|[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
|`none` {vbar} `normal` +
(default: _inherit_)
|[source]
header:
  font-kerning: none

|font-size
|xref:text.adoc#font-size[Font size] +
(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
|`bottom` {vbar} `middle` {vbar} `top` {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 the footer, it effectively disables the footer.

[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
|xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] +
(default: _not set_)
|[source]
footer:
  background-image: image:running-content.svg[fit=contain]

|border-color
|xref:blocks.adoc#border-color[Color] +
(default: `$base-border-color`)
|[source]
footer:
  border-color: #DDDDDD

|border-style
|xref:blocks.adoc#border-style[Border style] +
(default: `solid`)
|[source]
footer:
  border-style: dashed

|border-width
|xref:blocks.adoc#border-width[Measurement] {vbar} xref:blocks.adoc#border-width[Measurement[\]] +
(default: `0.5`)
|[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

|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
|`none` {vbar} `normal` +
(default: _inherit_)
|[source]
footer:
  font-kerning: none

|font-size
|xref:text.adoc#font-size[Font size] +
(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
|`bottom` {vbar} `middle` {vbar} `top` {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, background image, and border span the width of the page, set the margin to `0` and adjust the `content-margin` accordingly (typically `[0, inherit]`, which is the default).

[#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 between columns are only added if the `columns` key is specified.

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

Although not listed in the tables above, you can override the font settings (`font-family`, `font-size`, `font-color`, `font-style`, `text-transform`) for each page side for a running content periphery (e.g., `header-<side>-font-color`).
For example, you can set the font color used for the footer on recto pages as follows:

[,yaml]
----
footer:
  recto:
    font-color: #AA0000
----

[#position]
== <position>

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

Although not listed in the tables above, you can override individual font settings (`font-family`, `font-size`, `font-color`, `font-style`, `text-transform`) for each column position of a page side for a running content periphery (e.g., `header-<side>-<position>-font-color`).
For example, you can set the font color used for the right-hand column of the header on recto pages as follows:

[,yaml]
----
header:
  recto:
    right:
      font-color: #6CC644
      content: content with font color
----

[#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
|xref:add-running-content.adoc#start-at[Start page] {vbar} xref:add-running-content.adoc#page[Integer] +
(default: `body`)
|[source]
running-content:
  start-at: toc
|===

See xref:add-running-content.adoc#start-at[Start page] for more information about the `start-at` key, its values, and their requirements.