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

[#admonition]
== admonition

The keys in the `admonition` category control the arrangement and style of admonition blocks and the icon used for each admonition type.

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

|background-color
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
admontition:
  background-color: #757575

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

|border-radius
|xref:blocks.adoc#radius[Measurement] +
(default: _not set_)
|[source]
admonition:
  border-radius: 4

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

|border-width
|xref:blocks.adoc#border-width[Measurement] {vbar} xref:blocks.adoc#border-width[Measurement[\]] +
(default: _not set_)
|[source]
admonition:
  border-width: 0.5

// TODO What about admonition_rule_color which is used on line 106 in the admonition_spec.rb?

|column-rule-color
|xref:color.adoc[Color] +
(default: `'EEEEEE'`)
|[source]
admonition:
  column-rule-color: #AA0000

|column-rule-style
|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
(default: `solid`)
|[source]
admonition:
  column-rule-style: double

|column-rule-width
|xref:measurement-units.adoc[Measurement] +
(default: `0.5`)
|[source]
admonition:
  column-rule-width: 0.6

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

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

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

|font-size
|xref:text.adoc#font-size[Font size] +
(default: _inherit_)
|[source]
admonition:
  font-size: $base-font-size-large

|font-style
|xref:text.adoc#font-style[Font style] +
(default: _inherit_)
|[source]
admonition:
  font-style: italic

|padding
|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
(default: `[4, 12, 4, 12]`)
|[source]
admonition:
  padding: 1cm

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

[#label]
== admonition-label

The keys in the `admonition-label` category control the arrangement and style of the text-based labels on admonition blocks.

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

|font-color
|xref:color.adoc[Color] +
(default: _inherit_)
|[source]
admonition:
  label:
    font-color: #262626

|font-family
|xref:font-support.adoc[Font family name] +
(default: _inherit_)
|[source]
admonition:
  label:
    font-family: M+ 1p

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

|font-size
|xref:text.adoc#font-size[Font size] +
(default: _inherit_)
|[source]
admonition:
  label:
    font-size: 12

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

|min-width
|xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
admonition:
  label:
    min-width: 48

|<<padding,padding>>
|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top(n/a),right,bottom(n/a),left\]] +
(default: `$admonition-padding`)
|[source]
admonition:
  label:
    padding: [0, 12, 0, 12]

|text-align
|xref:text.adoc#text-align[Text alignment] +
(default: `center`)
|[source]
admonition:
  label:
    text-align: left

|text-transform
|xref:text.adoc#transform[Text transform] +
(default: `uppercase`)
|[source]
admonition:
  label:
    text-transform: lowercase

|vertical-align
|`bottom` {vbar} `middle` {vbar} `top` +
(default: `middle`)
|[source]
admonition:
  label:
    vertical-align: top
|===

[#padding]
=== padding

The top and bottom padding values are ignored on the `admonition-label-padding` key.

[#label-name]
== admonition-label-<name>

The keys in the `admonition-label-<name>` category control the arrangement and style of the text-based label that matches a built-in admonition name.
`<name>` can be `note`, `tip`, `warning`, `important`, or `caution`.

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

|font-color
|xref:color.adoc[Color] +
(default: _inherit_)
|[source]
admonition:
  label:
    caution:
      font-color: #262626

|font-family
|xref:font-support.adoc[Font family name] +
(default: _inherit_)
|[source]
admonition:
  label:
    important:
      font-family: M+ 1p

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

|font-size
|xref:text.adoc#font-size[Font size] +
(default: _inherit_)
|[source]
admonition:
  label:
    tip:
      font-size: 12

|font-style
|xref:text.adoc#font-style[Font style] +
(default: `bold`)
|[source]
admonition:
  label:
    tip:
      font-style: bold_italic

|text-transform
|xref:text.adoc#transform[Text transform] +
(default: `uppercase`)
|[source]
admonition:
  label:
    note:
      text-transform: lowercase
|===

[#icon-name]
== admonition-icon-<name>

The keys in the `admonition-icon-<name>` category control the arrangement and style of the specified icon associated with a built-in admonition name.
`<name>` can be `note`, `tip`, `warning`, `important`, or `caution`.
All icon types must be grouped under a single `icon` category.
In other words, the `icon` category _cannot_ be declared multiple times and its keys _cannot_ be flattened (e.g., `tip-name: far-lightbulb` is not valid syntax).

A font-based icon is placed in a container with a width 1.5 times the size of the icon.
This is done to give the icon more padding than the textual label.
This behavior will be configurable starting in Asciidoctor PDF 3.

The `image` key is only relevant when image-based icons are used (`icons=image`).
It's an alternative to using the `icon` attribute on the admonition block.
The path is resolved starting from the location of the AsciiDoc document and relative to the value of the `iconsdir` attribute.
The image macro syntax is not supported for this key.

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

|image
|path +
(default: _not set_)
|[source]
admonition:
  icon:
    tip:
      image: bulb.png

|<<name,name>>
|<icon set>-<icon name> +
(default: _not set_)
|[source]
admonition:
  icon:
    tip:
      name: fas-fire

|size
|xref:language.adoc#values[Number] +
(default: `24`)
|[source]
admonition:
  icon:
    note:
      size: 20

|stroke-color
|xref:color.adoc[Color] +
(default: caution=`#BF3400`; important=`#BF0000`; note=`#19407C`; tip=`#111111`; warning=`#BF6900`)
|[source]
admonition:
  icon:
    important:
      stroke-color: #FF0000
|===

[#name]
=== Identifying an icon

The `name` key assigned to a built-in admonition only accepts a value in the format of <icon set>-<icon name>`.
A value is always required when assigning an icon to a built-in admonition.
See the `.yml` files in the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon repository^] for a list of valid icon names.
The prefix (e.g., `fas-`) of the value determines which font set to use.
If the prefix is not specified, `fa-` is assumed.
