Running Content Category Keys

The header, footer, and running-content category keys control the arrangement and style of running header and footer content.

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

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.
Key Value Type Example

background-color

Color
(default: not set)

 
header:
  background-color: #EEEEEE
yaml

background-image

image macro | path
(default: not set)

 
header:
  background-image: image:running-content.svg[fit=contain]
yaml

border-color

Color
(default: $base-border-color)

 
header:
  border-color: #DDDDDD
yaml

border-style

Border style
(default: solid)

 
header:
  border-style: dashed
yaml

border-width

Measurement | Measurement[]
(default: not set)

 
header:
  border-width: 0.25
yaml

column-rule-color

Color
(default: not set)

 
header:
  column-rule-color: #CCCCCC
yaml

column-rule-spacing

Measurement
(default: 0)

 
header:
  column-rule-spacing: 5
yaml

column-rule-style

dashed | dotted | double | solid
(default: solid)

 
header:
  column-rule-style: dashed
yaml

column-rule-width

Measurement
(default: not set)

 
header:
  column-rule-width: 0.25
yaml

columns

Column specs triple
(default: not set)

 
header:
  columns: <50% =0% <50%
yaml

content-margin

Measurement | Measurement[top,right,bottom,left]
(default: [0, inherit])

 
header:
  content-margin: 0
yaml

font-color

Color
(default: inherit)

 
header:
  font-color: #333333
yaml

font-family

Font family name
(default: inherit)

 
header:
  font-family: Noto Serif
yaml

font-kerning

none | normal
(default: inherit)

 
header:
  font-kerning: none
yaml

font-size

Font size
(default: inherit)

 
header:
  font-size: 9
yaml

font-style

Font style
(default: inherit)

 
header:
  font-style: italic
yaml

height

Measurement
(default: not set)

 
header:
  height: 0.75in
yaml

image-vertical-align

bottom | middle | top | Measurement
(default: not set)

 
header:
  image-vertical-align: 4
yaml

line-height

Number
(default: $base-line-height)

 
header:
  line-height: 1.2
yaml

margin

Measurement | Measurement[top,right,bottom(n/a),left]
(default: [0, inherit])

 
header:
  margin: 0
yaml

padding

Measurement | Measurement[top,right,bottom,left]
(default: 0)

 
header:
  padding: [0, 3, 0, 3]
yaml

sectlevels

Integer
(default: 2)

 
header:
  sectlevels: 3
yaml

text-transform

Text transform
(default: none)

 
header:
  text-transform: uppercase
yaml

title-style

document | toc | basic
(default: document)

 
header:
  title-style: toc
yaml

vertical-align

top | middle | bottom | [top | middle | bottom, Measurement]
(default: middle)

 
header:
  vertical-align: middle
yaml

<side>-columns

Column specs triple
(default: not set)

 
header:
  recto:
    columns: <25% =50% >25%
yaml

<side>-content-margin

Measurement | Measurement[top,right,bottom,left]
(default: inherit)

 
header:
  recto:
    content-margin: [0, 0, 0, inherit]
yaml

<side>-margin

Measurement | Measurement[top,right,bottom(n/a),left]
(default: inherit)

 
header:
  recto:
    margin: [0, 0, 0, inherit]
yaml

<side>-padding

Measurement | Measurement[top,right,bottom,left]
(default: inherit)

 
header:
  recto:
    padding: [0, 3, 0, 3]
yaml

<side>-<position>-content

Quoted string
(default: '{page-number}')

 
header:
  recto:
    left:
      content: '{page-number}'
yaml

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

If you don’t specify a height for the footer, it effectively disables the footer.
Key Value Type Example

background-color

Color
(default: not set)

 
footer:
  background-color: #EEEEEE
yaml

background-image

image macro | path
(default: not set)

 
footer:
  background-image: image:running-content.svg[fit=contain]
yaml

border-color

Color
(default: $base-border-color)

 
footer:
  border-color: #DDDDDD
yaml

border-style

Border style
(default: solid)

 
footer:
  border-style: dashed
yaml

border-width

Measurement | Measurement[]
(default: 0.5)

 
footer:
  border-width: 0.25
yaml

column-rule-color

Color
(default: not set)

 
footer:
  column-rule-color: #CCCCCC
yaml

column-rule-spacing

Measurement
(default: 0)

 
footer:
  column-rule-spacing: 5
yaml

column-rule-style

dashed | dotted | double | solid
(default: solid)

 
footer:
  column-rule-style: dashed
yaml

column-rule-width

Measurement
(default: not set)

 
footer:
  column-rule-width: 0.25
yaml

columns

Column specs triple
(default: not set)

 
footer:
  columns: <50% =0% <50%
yaml

content-margin

Measurement | Measurement[top,right,bottom,left]
(default: [0, inherit])

 
footer:
  content-margin: 0
yaml

font-color

Color
(default: inherit)

 
footer:
  font-color: #333333
yaml

font-family

Font family name
(default: inherit)

 
footer:
  font-family: Noto Serif
yaml

font-kerning

none | normal
(default: inherit)

 
footer:
  font-kerning: none
yaml

font-size

Font size
(default: inherit)

 
footer:
  font-size: 9
yaml

font-style

Font style
(default: inherit)

 
footer:
  font-style: italic
yaml

height

Measurement
(default: not set)

 
footer:
  height: 0.75in
yaml

image-vertical-align

bottom | middle | top | Measurement
(default: not set)

 
footer:
  image-vertical-align: 4
yaml

line-height

Number
(default: $base-line-height)

 
footer:
  line-height: 1.2
yaml

margin

Measurement | Measurement[top(n/a),right,bottom,left]
(default: [0, inherit])

 
footer:
  margin: 0
yaml

padding

Measurement | Measurement[top,right,bottom,left]
(default: 0)

 
footer:
  padding: [0, 3, 0, 3]
yaml

sectlevels

Integer
(default: 2)

 
footer:
  sectlevels: 3
yaml

text-transform

Text transform
(default: none)

 
footer:
  text-transform: uppercase
yaml

title-style

document | toc | basic
(default: document)

 
footer:
  title-style: toc
yaml

vertical-align

top | middle | bottom | [top | middle | bottom, Measurement]
(default: middle)

 
footer:
  vertical-align: top
yaml

<side>-columns

Column specs triple
(default: not set)

 
footer:
  verso:
    columns: <50% =0% <50%
yaml

<side>-content-margin

Measurement | Measurement[top,right,bottom,left]
(default: inherit)

 
footer:
  verso:
    content-margin: [0, inherit, 0, 0]
yaml

<side>-margin

Measurement | Measurement[top (n/a),right,bottom,left]
(default: [0, inherit])

 
footer:
  verso:
    margin: [0, inherit, 0, 0]
yaml

<side>-padding

Measurement | Measurement[top,right,bottom,left]
(default: inherit)

 
footer:
  verso:
    padding: [0, 3, 0, 3]
yaml

<side>-<position>-content

Quoted string
(default: '{page-number}')

 
footer:
  verso:
    center:
      content: '{page-number}'
yaml

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

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

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

padding

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

sectlevels

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

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

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:

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

running-content

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

Key Value Type Example

start-at

Start page | Integer
(default: body)

 
running-content:
  start-at: toc
yaml

See Start page for more information about the start-at key, its values, and their requirements.