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
yaml

border-color

Color
(default: not set)

 
image:
  border-color: #CCCCCC
yaml

border-fit

content | auto
(default: content)

 
image:
  border-fit: auto
yaml

border-radius

Measurement
(default: not set)

 
image:
  border-radius: 2
yaml

border-style

Border style
(default: solid)

 
image:
  border-style: dashed
yaml

border-width

Measurement | Measurement[]
(default: not set)

 
image:
  border-width: 0.5
yaml

float-gap

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

 
image:
  float-gap: 12
yaml

width

Measurement
(default: not set)

 
image:
  width: 100%
yaml

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]
asciidoc

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})"
yaml

font-color

Color
(default: inherit)

 
image:
  alt:
    font-color: #FF0000
yaml

font-family

Font family name
(default: inherit)

 
image:
  alt:
    font-family: Courier
yaml

font-kerning

normal | none
(default: inherit)

 
image:
  alt:
    font-kerning: none
yaml

font-size

Font size
(default: inherit)

 
image:
  alt:
    font-size: 9
yaml

font-style

Font style
(default: normal)

 
image:
  alt:
    font-style: italic
yaml

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
yaml

caption-end

End placement
(default: bottom)

 
image:
  caption:
    end: top
yaml

caption-max-width

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

 
image:
  caption:
    max-width: fit-content
yaml

caption-text-align

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

 
image:
  caption:
    text-align: center
yaml