Heading Category Keys

heading

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

Key Value Type Example

font-color

Color
(default: inherit)

 
heading:
  font-color: #222222

font-family

Font family name
(default: inherit)

 
heading:
  font-family: Noto Serif

font-kerning

none | normal
(default: inherit)

 
heading:
  font-kerning: none

font-style

Font style
(default: bold)

 
heading:
  font-style: italic

line-height

Number
(default: 1.15)

 
heading:
  line-height: 1.2

margin-bottom

Measurement
(default: 12)

 
heading:
  margin-bottom: 6

margin-page-top

Measurement
(default: 0)

 
heading:
  margin-page-top: 12

margin-top

Measurement
(default: 4)

 
heading:
  margin-top: 6

min-height-after

Measurement | auto
(default: 20)

 
heading:
  min-height-after: 0.5in

text-align

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

 
heading:
  text-align: center

text-decoration

Text decoration
(default: none)

 
heading:
  text-decoration: underline

text-decoration-color

Color
(default: $heading-font-color)

 
heading:
  text-decoration-color: #CCCCCC

text-decoration-width

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

 
heading:
  text-decoration-width: 0.5

text-transform

Text transform
(default: inherit)

 
heading:
  text-transform: capitalize

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

border-style

Border style
(default: solid)

 
heading:
  h2-border-style: dashed

border-width

Measurement | Measurement[]
(default: not set)

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

font-color

Color
(default: $heading-font-color)

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

font-family

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

 
heading:
  h4-font-family: Roboto

font-kerning

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

 
heading:
  h3-font-kerning: none

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

font-style

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

 
heading:
  h3-font-style: bold_italic

margin-bottom

Measurement
(default: $heading-margin-bottom)

 
heading:
  h2-margin-bottom: 10

margin-page-top

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

 
heading:
  h2-margin-page-top: 12

margin-top

Measurement
(default: $heading-margin-top)

 
heading:
  h2-margin-top: 6

padding

Measurement | Measurement[]
(default: not set)

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

text-align

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

 
heading:
  h2-text-align: center

text-decoration

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

 
heading:
  h4-text-decoration: underline

text-decoration-color

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

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

text-decoration-width

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

 
heading:
  h4-text-decoration-width: 0.2

text-transform

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

 
heading:
  h3-text-transform: smallcaps

min-height-after

The min-height-after key specifies how much space to reserve below a section title or discrete heading (starting from where the bottom margin ends) for content to fit below it. If the available space on the page is less than this value, then the heading will automatically be advanced to the next page.

heading:
  min-height-after: 0.25in

Rather than specifying a fixed value, you can configure the converter to ensure at least one line of content is rendered below the heading by setting the value to auto.

heading:
  min-height-after: auto

The min-height-after value is ignored if the section is empty or the discrete heading is the last child of its parent.

A section title and discrete heading that wraps is always advanced to the next page if it avoids it being split across pages.

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

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

break-before

always | auto
(default: always)

 
heading:
  part:
    break-before: auto