Heading Category Keys

heading

The keys in the heading category control the style of most headings, including part titles, chapter titles, sections titles, the title of the table of contents, and discrete headings.

Key Value Type Example

font-color

Color
(default: inherit)

 
heading:
  font-color: #222222
yaml

font-family

Font family name
(default: inherit)

 
heading:
  font-family: Noto Serif
yaml

font-kerning

none | normal
(default: inherit)

 
heading:
  font-kerning: none
yaml

font-style

Font style
(default: bold)

 
heading:
  font-style: italic
yaml

line-height

Number
(default: 1.15)

 
heading:
  line-height: 1.2
yaml

margin-bottom

Measurement
(default: 12)

 
heading:
  margin-bottom: 6
yaml

margin-page-top

Measurement
(default: 0)

 
heading:
  margin-page-top: 12
yaml

margin-top

Measurement
(default: 4)

 
heading:
  margin-top: 6
yaml

min-height-after

Measurement | auto
(default: 20)

 
heading:
  min-height-after: 0.5in
yaml

text-align

Text alignment
(default: $base-text-align)

 
heading:
  text-align: center
yaml

text-decoration

Text decoration
(default: none)

 
heading:
  text-decoration: underline
yaml

text-decoration-color

Color
(default: $heading-font-color)

 
heading:
  text-decoration-color: #CCCCCC
yaml

text-decoration-width

Number
(default: $base-text-decoration-width)

 
heading:
  text-decoration-width: 0.5
yaml

text-transform

Text transform
(default: inherit)

 
heading:
  text-transform: capitalize
yaml

heading-h<n>

The keys in the heading-h<n> category control the style of a heading level. <n> is a number ranging from 1 to 6, representing each of the six heading levels. The heading-h1 key controls the font properties of the document title (doctitle) when the doctype is article and the title page isn’t enabled (i.e., the title-page document attribute isn’t set). When the doctype is book, the heading-h1 key controls the properties for part titles and the heading-h2 key controls the properties of chapter titles.

Key Value Type Example

border-color

Color
(default: not set)

 
heading:
  h2-border-color: #AA0000
yaml

border-style

Border style
(default: solid)

 
heading:
  h2-border-style: dashed
yaml

border-width

Measurement | Measurement[]
(default: not set)

 
heading:
  h2-border-width: [0, 0, 1, 0]
yaml

font-color

Color
(default: $heading-font-color)

 
heading:
  h2-font-color: [0, 99%, 100%, 0]
yaml

font-family

Font family name
(default: $heading-font-family)

 
heading:
  h4-font-family: Roboto
yaml

font-kerning

none | normal
(default: $heading-font-kerning)

 
heading:
  h3-font-kerning: none
yaml

font-size

Font size
(default: h1=24; h2=18; h3=16; h4=14; <h5=12; h6=10)

 
heading:
  h6-font-size: $base-font-size * 1.7
yaml

font-style

Font style
(default: $heading-font-style)

 
heading:
  h3-font-style: bold_italic
yaml

margin-bottom

Measurement
(default: $heading-margin-bottom)

 
heading:
  h2-margin-bottom: 10
yaml

margin-page-top

Measurement
(default: $heading-margin-page-top)

 
heading:
  h2-margin-page-top: 12
yaml

margin-top

Measurement
(default: $heading-margin-top)

 
heading:
  h2-margin-top: 6
yaml

padding

Measurement | Measurement[]
(default: not set)

 
heading:
  h2-padding: [0, 2, 0, 6]
yaml

text-align

Text alignment
(default: $heading-text-align)

 
heading:
  h2-text-align: center
yaml

text-decoration

Text decoration
(default: $heading-text-decoration)

 
heading:
  h4-text-decoration: underline
yaml

text-decoration-color

Color
(default: $heading-text-decoration-color)

 
heading:
  h4-text-decoration-color: #4C516D
yaml

text-decoration-width

Number
(default: $heading-text-decoration-width)

 
heading:
  h4-text-decoration-width: 0.2
yaml

text-transform

Text transform
(default: $heading-text-transform)

 
heading:
  h3-text-transform: uppercase
yaml

padding

The padding key is only intended to be used to offset the border by a fixed amount. If you want to put spacing around the top and bottom edges of the heading container, you should use the margin-* keys instead.

h<n>-font-size

A font size is assigned to each heading level by the base theme. If you want the font size of a specific level to be inherited, you must assign the value null (or ~ for short) to the h<n>-font-size.

heading-chapter

The key in the heading-chapter category controls the page break behavior before a chapter title. The doctype must be book for the heading-chapter key to take effect.

Key Value Type Example

break-before

always | auto
(default: always)

 
heading:
  chapter:
    break-before: auto
yaml

heading-part

The keys in the heading-part category control the page break behavior before and after a part title. The doctype must be book for the heading-part keys to take effect.

Key Value Type Example

break-after

always | avoid | auto
(default: auto)

 
heading:
  part:
    break-after: always
yaml

break-before

always | auto
(default: always)

 
heading:
  part:
    break-before: auto
yaml