Block Image Styles

In general, the Block Styles 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 Block Image Category Keys. The following sections provide information and examples of the keys and values that are unique to the block images.

Caption alignment

In addition to the standard block alignment keywords (center, left, and right), the caption-align key accepts the keyword inherit when it is set on the image category.

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 key aligns text within the text box of the caption block using text alignment rules.

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.

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.

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.

image:
  caption:
    end: bottom

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 usual text alignment values when it is set on the image category.

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 key aligns a caption block horizontally within its container.

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.