Admonition Category Keys

admonition

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

Key Value Type Example

background-color

Color
(default: not set)

 
admontition:
  background-color: #757575

border-color

Color
(default: not set)

 
admonition:
  border-color: #E6E8FA

border-radius

Measurement
(default: not set)

 
admonition:
  border-radius: 4

border-style

Border style
(default: solid)

 
admonition:
  border-style: dashed

border-width

Measurement | Measurement[]
(default: not set)

 
admonition:
  border-width: 0.5

column-rule-color

Color
(default: 'EEEEEE')

 
admonition:
  column-rule-color: #AA0000

column-rule-style

dashed | dotted | double | solid
(default: solid)

 
admonition:
  column-rule-style: double

column-rule-width

Measurement
(default: 0.5)

 
admonition:
  column-rule-width: 0.6

font-color

Color
(default: inherit)

 
admonition:
  font-color: #999999

font-family

Font family name
(default: inherit)

 
admonition:
  font-family: Noto Sans

font-kerning

none | normal
(default: inherit)

 
admonition:
  font-kerning: none

font-size

Font size
(default: inherit)

 
admonition:
  font-size: $base-font-size-large

font-style

Font style
(default: inherit)

 
admonition:
  font-style: italic

padding

Measurement | Measurement[]
(default: [4, 12, 4, 12])

 
admonition:
  padding: 1cm

text-transform

Text transform
(default: inherit)

 
admonition:
  text-transform: none

admonition-label

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

Key Value Type Example

font-color

Color
(default: inherit)

 
admonition:
  label:
    font-color: #262626

font-family

Font family name
(default: inherit)

 
admonition:
  label:
    font-family: M+ 1p

font-kerning

none | normal
(default: inherit)

 
admonition:
  label:
    font-kerning: none

font-size

Font size
(default: inherit)

 
admonition:
  label:
    font-size: 12

font-style

Font style
(default: bold)

 
admonition:
  label:
    font-style: bold_italic

min-width

Measurement
(default: not set)

 
admonition:
  label:
    min-width: 48

padding

Measurement | Measurement[top(n/a),right,bottom(n/a),left]
(default: $admonition-padding)

 
admonition:
  label:
    padding: [0, 12, 0, 12]

text-align

Text alignment
(default: center)

 
admonition:
  label:
    text-align: left

text-transform

Text transform
(default: uppercase)

 
admonition:
  label:
    text-transform: lowercase

vertical-align

bottom | middle | top
(default: middle)

 
admonition:
  label:
    vertical-align: top

padding

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

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.

Key Value Type Example

font-color

Color
(default: inherit)

 
admonition:
  label:
    caution:
      font-color: #262626

font-family

Font family name
(default: inherit)

 
admonition:
  label:
    important:
      font-family: M+ 1p

font-kerning

none | normal
(default: inherit)

 
admonition:
  label:
    warning:
      font-kerning: none

font-size

Font size
(default: inherit)

 
admonition:
  label:
    tip:
      font-size: 12

font-style

Font style
(default: bold)

 
admonition:
  label:
    tip:
      font-style: bold_italic

text-transform

Text transform
(default: uppercase)

 
admonition:
  label:
    note:
      text-transform: lowercase

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.

Key Value Type Example

image

path
(default: not set)

 
admonition:
  icon:
    tip:
      image: bulb.png

name

<icon set>-<icon name>
(default: not set)

 
admonition:
  icon:
    tip:
      name: fas-fire

size

Number
(default: 24)

 
admonition:
  icon:
    note:
      size: 20

stroke-color

Color
(default: caution=#BF3400; important=#BF0000; note=#19407C; tip=#111111; warning=#BF6900)

 
admonition:
  icon:
    important:
      stroke-color: #FF0000

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 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.

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 theme admonition per type use case on the Extended Converter Use Cases page. To apply the extension, refer to Use the Extended Converter.