= Block Image Styles
:description: In addition to the general block and caption keys, the theming language provides keys for arranging and styling block images, alt text, and image captions.

In general, the xref:blocks.adoc[] apply to block images and their captions.
You can further customize how the block images, alt text, and captions are arranged and styled using the xref:block-image.adoc[].
The following sections provide information and examples of the keys and values that are unique to the block images.

[#caption-align]
== Caption alignment

In addition to the xref:blocks.adoc#align[standard block alignment keywords (center, left, and right)], the `caption-align` key accepts the keyword `inherit` when it is set on the `image` category.

[,yaml]
----
image:
  caption:
    align: inherit
----

When the value is `inherit`, the key will inherit the alignment assigned to the image itself (`image-align`).
The `caption-align` key is distinct from the similarly-named `caption-text-align` key.
The <<caption-text-align,caption-text-align key>> aligns text within the text box of the caption block using text alignment rules.

[#fallback]
== Fallback image width

To scale all block images that don't define either a `pdfwidth` or `scaledwidth` attribute on an image macro in your document, assign a value to the `image-width` key in your theme file.

[,yaml]
----
image:
  width: 100%
----

The `image-width` key accepts the same values as the `pdfwidth` attribute.
Thus, you can think of it as the fallback value for the `pdfwidth` attribute.
If specified, the `image-width` value takes precedence over the `width` attribute on an image macro.

[#end]
== Caption end

The `caption-end` key specifies whether the image caption is located on top or below the image.
The key accepts the following keywords:

bottom:: The caption block is placed below the image.
top:: The caption block is place above the image.

[,yaml]
----
image:
  caption:
    end: bottom
----

[#caption-text-align]
== Caption text alignment

The `caption-text-align` key controls the alignment of the caption text within the bounds of the caption.
The key accepts the keyword `inherit` in addition to the xref:text.adoc#text-align[usual text alignment values] when it is set on the `image` category.

[,yaml]
----
image:
  caption:
    text-align: inherit
----

When the value is `inherit`, the key will inherit the alignment assigned to the image itself (`image-align`).

The `caption-text-align` key is distinct from the similarly-named `caption-align` key.
The <<caption-align,caption-align key>> aligns a caption block horizontally within its container.

[#caption-max-width]
=== Caption max width

In order for an image to be sized and positioned correctly when `max-width` is `fit-content`, a width should always be specified on the image.
This is especially true for "`keep together`" logic to work correctly.
The arranger cannot know the height of the image plus caption unless it knows how much space the caption will need, and that can't be known when `max-width` is `fit-content` until the width of the image is known.
Thus, we recommend that you always specify the width of an image, preferably using the `pdfwidth` attribute.