path: root/docs/modules/theme/pages/admonition.adoc

= 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.
The width is controlled by the `width` key.
The `width` key is only used for image-based icons.

[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

|scale
|Number in range (0,1] +
(default: `2 / 3`)
|[source]
admonition:
  icon:
    note:
      scale: 1

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

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

|width
|xref:measurement-units.adoc[Measurement] +
(default: `36`)
|[source]
admonition:
  icon:
    important:
      width: 24
|===

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

[#name]
== admonition-<name>

Asciidoctor PDF does not currently support theming admonitions by name (i.e., type).
In other words, the theming system doesn't provide the `admonition-<name>` category key, where `<name>` is the admonition name (e.g., note, tip, etc).
That means it's not possible to apply a background color to one admonition type, such as NOTE, without applying it to all admonitions.
However, it is possible to extend Asciidoctor PDF to add this capability.

In order to add support for the `admonition-<name>` category key to the theming system, you need to create an extended converter.
That converter will intercept requests to convert an admonition and temporarily promote settings on the `admonition-<name>` category key to the `admonition` category key.
Once the admonition is converted (i.e., rendered), the original theme settings will be restored.

You can find the details of this extended converter in the xref:extend:use-cases.adoc#theme-admonition-per-type[theme admonition per type] use case on the xref:extend:use-cases.adoc[] page.
To apply the extension, refer to xref:extend:use-converter.adoc[].