= 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 is used to define the number of columns, the named position of those columns, as well as each column's width and alignment.
The columns are defined using space-seprated (or comma-seperated) colspecs.
The maximum number of columns is 3.
The column's name is infered by the position of the colspec in the list (center for 1 column, left and right for 2 columns, and left, center, and right for 3 columns).

A colspec defines the width of the column and an optional alignment.
The width is represented in percentage of available space (the space from the left margin to the right margin).
The alignment is represented as a symbol, `<`, `=`, `>` to represent left, center, and right, respectively.
If the alignment isn't specfied, it defaults to `<`.

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

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