= Heading Category Keys
:description: Reference list of the available heading category keys and their value types.
:navtitle: Heading
:source-language: yaml

[#heading]
== 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.

[cols="3,4,5a"]
|===
|Key |Value Type |Example

|font-color
|xref:color.adoc[Color] +
(default: _inherit_)
|[source]
heading:
  font-color: #222222

|font-family
|xref:font-support.adoc[Font family name] +
(default: _inherit_)
|[source]
heading:
  font-family: Noto Serif

|font-kerning
|`none` {vbar} `normal` +
(default: _inherit_)
|[source]
heading:
  font-kerning: none

|font-style
|xref:text.adoc#font-style[Font style] +
(default: `bold`)
|[source]
heading:
  font-style: italic

|line-height
|xref:language.adoc#values[Number] +
(default: `1.15`)
|[source]
heading:
  line-height: 1.2

|margin-bottom
|xref:measurement-units.adoc[Measurement] +
(default: `12`)
|[source]
heading:
  margin-bottom: 6

|margin-page-top
|xref:measurement-units.adoc[Measurement] +
(default: `0`)
|[source]
heading:
  margin-page-top: 12

|margin-top
|xref:measurement-units.adoc[Measurement] +
(default: `4`)
|[source]
heading:
  margin-top: 6

|<<min-height-after>>
|xref:measurement-units.adoc[Measurement] {vbar} auto +
(default: `20`)
|[source]
heading:
  min-height-after: 0.5in

|text-align
|xref:text.adoc#text-align[Text alignment] +
(default: `$base-text-align`)
|[source]
heading:
  text-align: center

|text-decoration
|xref:text.adoc#decoration[Text decoration] +
(default: `none`)
|[source]
heading:
  text-decoration: underline

|text-decoration-color
|xref:color.adoc[Color] +
(default: `$heading-font-color`)
|[source]
heading:
  text-decoration-color: #CCCCCC

|text-decoration-width
|xref:language.adoc#values[Number] +
(default: `$base-text-decoration-width`)
|[source]
heading:
  text-decoration-width: 0.5

|text-transform
|xref:text.adoc#transform[Text transform] +
(default: _inherit_)
|[source]
heading:
  text-transform: capitalize
|===

[#level]
== 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.

[cols="3,4,5a"]
|===
|Key |Value Type |Example

|border-color
|xref:blocks.adoc#border-color[Color] +
(default: _not set_)
|[source]
heading:
  h2-border-color: #AA0000

|border-style
|xref:blocks.adoc#border-style[Border style] +
(default: `solid`)
|[source]
heading:
  h2-border-style: dashed

|border-width
|xref:blocks.adoc#border-width[Measurement] {vbar} xref:blocks.adoc#border-width[Measurement[\]] +
(default: _not set_)
|[source]
heading:
  h2-border-width: [0, 0, 1, 0]

|font-color
|xref:color.adoc[Color] +
(default: `$heading-font-color`)
|[source]
heading:
  h2-font-color: [0, 99%, 100%, 0]

|font-family
|xref:font-support.adoc[Font family name] +
(default: `$heading-font-family`)
|[source]
heading:
  h4-font-family: Roboto

|font-kerning
|`none` {vbar} `normal` +
(default: `$heading-font-kerning`)
|[source]
heading:
  h3-font-kerning: none

|<<font-size,font-size>>
|xref:text.adoc#font-size[Font size] +
(default: h1=`24`; h2=`18`; h3=`16`; h4=`14`; <h5=`12`; h6=`10`)
|[source]
heading:
  h6-font-size: $base-font-size * 1.7

|font-style
|xref:text.adoc#font-style[Font style] +
(default: `$heading-font-style`)
|[source]
heading:
  h3-font-style: bold_italic

|margin-bottom
|xref:measurement-units.adoc[Measurement] +
(default: `$heading-margin-bottom`)
|[source]
heading:
  h2-margin-bottom: 10

|margin-page-top
|xref:measurement-units.adoc[Measurement] +
(default: `$heading-margin-page-top`)
|[source]
heading:
  h2-margin-page-top: 12

|margin-top
|xref:measurement-units.adoc[Measurement] +
(default: `$heading-margin-top`)
|[source]
heading:
  h2-margin-top: 6

|<<padding,padding>>
|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
(default: _not set_)
|[source]
heading:
  h2-padding: [0, 2, 0, 6]

|text-align
|xref:text.adoc#text-align[Text alignment] +
(default: `$heading-text-align`)
|[source]
heading:
  h2-text-align: center

|text-decoration
|xref:text.adoc#decoration[Text decoration] +
(default: `$heading-text-decoration`)
|[source]
heading:
  h4-text-decoration: underline

|text-decoration-color
|xref:color.adoc[Color] +
(default: `$heading-text-decoration-color`)
|[source]
heading:
  h4-text-decoration-color: #4C516D

|text-decoration-width
|xref:language.adoc#values[Number] +
(default: `$heading-text-decoration-width`)
|[source]
heading:
  h4-text-decoration-width: 0.2

|text-transform
|xref:text.adoc#transform[Text transform] +
(default: `$heading-text-transform`)
|[source]
heading:
  h3-text-transform: smallcaps
|===

[#min-height-after]
=== 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.

[,yaml]
----
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`.

[,yaml]
----
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]
=== 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.

[#font-size]
=== 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`.

[#chapter]
== 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.

[cols="3,4,5a"]
|===
|Key |Value Type |Example

|break-before
|`always` {vbar} `auto` +
(default: `always`)
|[source]
heading:
  chapter:
    break-before: auto
|===

[#part]
== 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.

[cols="3,4,5a"]
|===
|Key |Value Type |Example

|break-after
|`always` {vbar} `avoid` {vbar} `auto` +
(default: `auto`)
|[source]
heading:
  part:
    break-after: always

|break-before
|`always` {vbar} `auto` +
(default: `always`)
|[source]
heading:
  part:
    break-before: auto
|===