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

background-image

image macro | path
(default: not set)

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

border-color

Color
(default: $base-border-color)

 
header:
  border-color: #DDDDDD

border-style

Border style
(default: solid)

 
header:
  border-style: dashed

border-width

Measurement | Measurement[]
(default: not set)

 
header:
  border-width: 0.25

column-rule-color

Color
(default: not set)

 
header:
  column-rule-color: #CCCCCC

column-rule-spacing

Measurement
(default: 0)

 
header:
  column-rule-spacing: 5

column-rule-style

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

 
header:
  column-rule-style: dashed

column-rule-width

Measurement
(default: not set)

 
header:
  column-rule-width: 0.25

columns

Column specs triple
(default: not set)

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

content-margin

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

 
header:
  content-margin: 0

font-color

Color
(default: inherit)

 
header:
  font-color: #333333

font-family

Font family name
(default: inherit)

 
header:
  font-family: Noto Serif

font-kerning

none | normal
(default: inherit)

 
header:
  font-kerning: none

font-size

Font size
(default: inherit)

 
header:
  font-size: 9

font-style

Font style
(default: inherit)

 
header:
  font-style: italic

height

Measurement
(default: not set)

 
header:
  height: 0.75in

image-vertical-align

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

 
header:
  image-vertical-align: 4

line-height

Number
(default: $base-line-height)

 
header:
  line-height: 1.2

margin

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

 
header:
  margin: 0

padding

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

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

sectlevels

Integer
(default: 2)

 
header:
  sectlevels: 3

text-transform

Text transform
(default: none)

 
header:
  text-transform: uppercase

title-style

document | toc | basic
(default: document)

 
header:
  title-style: toc

vertical-align

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

 
header:
  vertical-align: middle

<side>-columns

Column specs triple
(default: not set)

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

<side>-content-margin

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

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

<side>-margin

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

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

<side>-padding

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

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

<side>-<position>-content

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

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

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

background-image

image macro | path
(default: not set)

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

border-color

Color
(default: $base-border-color)

 
footer:
  border-color: #DDDDDD

border-style

Border style
(default: solid)

 
footer:
  border-style: dashed

border-width

Measurement | Measurement[]
(default: 0.5)

 
footer:
  border-width: 0.25

column-rule-color

Color
(default: not set)

 
footer:
  column-rule-color: #CCCCCC

column-rule-spacing

Measurement
(default: 0)

 
footer:
  column-rule-spacing: 5

column-rule-style

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

 
footer:
  column-rule-style: dashed

column-rule-width

Measurement
(default: not set)

 
footer:
  column-rule-width: 0.25

columns

Column specs triple
(default: not set)

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

content-margin

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

 
footer:
  content-margin: 0

font-color

Color
(default: inherit)

 
footer:
  font-color: #333333

font-family

Font family name
(default: inherit)

 
footer:
  font-family: Noto Serif

font-kerning

none | normal
(default: inherit)

 
footer:
  font-kerning: none

font-size

Font size
(default: inherit)

 
footer:
  font-size: 9

font-style

Font style
(default: inherit)

 
footer:
  font-style: italic

height

Measurement
(default: not set)

 
footer:
  height: 0.75in

image-vertical-align

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

 
footer:
  image-vertical-align: 4

line-height

Number
(default: $base-line-height)

 
footer:
  line-height: 1.2

margin

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

 
footer:
  margin: 0

padding

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

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

sectlevels

Integer
(default: 2)

 
footer:
  sectlevels: 3

text-transform

Text transform
(default: none)

 
footer:
  text-transform: uppercase

title-style

document | toc | basic
(default: document)

 
footer:
  title-style: toc

vertical-align

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

 
footer:
  vertical-align: top

<side>-columns

Column specs triple
(default: not set)

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

<side>-content-margin

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

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

<side>-margin

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

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

<side>-padding

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

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

<side>-<position>-content

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

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

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

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

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