Block Image Category Keys

image

The keys in the image category control the arrangement and style of block images.

Key Value Type Example

align

Block alignment
(default: left)

 
image:
  align: right

border-color

Color
(default: not set)

 
image:
  border-color: #CCCCCC

border-fit

content | auto
(default: content)

 
image:
  border-fit: auto

border-radius

Measurement
(default: not set)

 
image:
  border-radius: 2

border-style

Border style
(default: solid)

 
image:
  border-style: dashed

border-width

Measurement | Measurement[]
(default: not set)

 
image:
  border-width: 0.5

float-gap

Measurement | Measurement[side,bottom]
(default: [12, 6])

 
image:
  float-gap: 12

width

Measurement
(default: not set)

 
image:
  width: 100%

noborder role

If the noborder role is present on a block image, the border is not drawn on that image even if the border-related keys are defined on the image category in the theme.

image::image-without-border.png[role=noborder]

border-color

A border is applied to a block image if border-color is specified, border-width is specified, the value of border-width is greater than zero, and the noborder role isn’t present. The border is drawn above the image on the inside of the box reserved for the image.

border-fit

When the value auto is assigned to the border-fit key the border will expand to fit the width of the container (i.e., full width) instead of the image.

width

The width key only applies to block images that don’t have either a pdfwidth or scaledwidth attribute on the image macro. If width is specified, its value takes precedence over the value of the width attribute on the image macro, but not over the value of the pdfwidth or scaledwidth attributes. The width key accepts the same values as the pdfwidth attribute.

image-alt

The keys in the image-alt category control the arrangement and style of the alt text of block images.

Key Value Type Example

content

Quoted string
(default: "%{link}[%{alt}]%{/link} | %{target}")

 
image:
  alt:
    content: "%{alt} (%{target})"

font-color

Color
(default: inherit)

 
image:
  alt:
    font-color: #FF0000

font-family

Font family name
(default: inherit)

 
image:
  alt:
    font-family: Courier

font-kerning

normal | none
(default: inherit)

 
image:
  alt:
    font-kerning: none

font-size

Font size
(default: inherit)

 
image:
  alt:
    font-size: 9

font-style

Font style
(default: normal)

 
image:
  alt:
    font-style: italic

content

The content key accepts the placeholders %{alt}, %{target}, %{link}, and %{/link}. These placeholders insert the alt text, image target, and link open and close tags into the content template.

image-caption

The keys in the image-caption category control the arrangement and style of the captions for block images. Most of the keys listed on Caption Category Keys can also be nested under the image-caption category to further customize the image captions.

Key Value Type Example

caption-align

Block alignment | inherit
(default: $caption-align)

 
image:
  caption:
    align: inherit

caption-end

End placement
(default: bottom)

 
image:
  caption:
    end: top

caption-max-width

fit-content | fit-content(percentage) | none | Measurement
(default: none)

 
image:
  caption:
    max-width: fit-content

caption-text-align

Text alignment | inherit
(default: $image-caption-align)

 
image:
  caption:
    text-align: center