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

The keys in the `caption` category control the arrangement and style of block captions globally.
Many of these keys can be customized <<per-block,per block>>.

[#caption]
== caption

TIP: The `caption-align` and `caption-text-align` keys on the `image` and `table` categories also accept the value `inherit`.
See xref:block-images.adoc[] and xref:tables.adoc[] for more information about setting `inherit` on their captions.

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

|align
|xref:blocks.adoc#align[Block alignment] +
(default: `left`)
|[source]
caption:
  align: right

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

|end
|top {vbar} bottom +
(default: _varies by block_)
|[source]
caption:
  end: bottom

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

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

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

|font-size
|xref:text.adoc#font-size[Font size] +
(default: _inherit_)
|[source]
caption:
  font-size: 11

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

|margin-inside
|xref:measurement-units.adoc[Measurement] +
(default: `4`)
|[source]
caption:
  margin-inside: 3

|margin-outside
|xref:measurement-units.adoc[Measurement] +
(default: `0`)
|[source]
caption:
  margin-outside: 0

|text-align
|xref:text.adoc#text-align[Text alignment] +
(default: `$<category>-caption-align` or `$caption-align`)
|[source]
caption:
  text-align: right

|text-decoration
|xref:text.adoc#decoration[Text decoration] +
(default: `none`)
|[source]
caption:
  text-decoration: line-through

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

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

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

[#per-block]
== Caption per block

In addition to the global `caption` category, each of the keys listed in <<caption>>, except for the `text-decoration` keys, can be set on the caption key nested inside the following block categories:

* `code`
* `example`
* `footnotes`
* `image`
* `quote`
* `table`
* `verse`

For example, to configure the caption just for code blocks, use the following declaration:

[,yaml]
----
code:
  caption:
    background-color: #FF0000
    font-color: #FFFFFF
    font-size: 1em
    font-style: bold
----

If a key is not specified on a block category, the key from the global `caption` category will be used as a fallback.