Figure

A figure shows an image with the text around it: an alternative, a caption, and a credit. It can reserve layout space with its width and height, load lazily, and swap to another image in dark mode.

Syntax

A container directive with a caption in the body:

:::figure{src="/images/architecture.svg" alt="Three boxes in a row."}
The build reads the site, the theme, and the content.
:::

Or a leaf directive with caption:

::figure{src="/images/architecture.svg" alt="Three boxes in a row." caption="The build pipeline"}

Options

Name	Type	Default	What it does
src	string	required	The image. Without it the figure renders nothing.
src_dark	string	none	The image shown in dark mode. It is a second visual source only: one wrapper carries the accessible name. When it equals src, one image is used in both modes.
alt	string	empty	The text alternative. It is exposed once for the figure, whatever theme is shown. An empty value marks the image as decorative.
caption	string	the body	The caption text. The body is used when caption is absent.
credit	string	none	Who made the image, shown under the caption.
credit_url	http or https URL	none	Makes the credit a link.
srcset	string	none	Responsive image candidates for src.
sizes	string	none	The layout hint for srcset.
width, height	whole number	none	Intrinsic size in pixels, so the layout does not shift when the image loads.
loading	lazy or eager	lazy	Use eager for an image above the fold.
decoding	async, sync, or auto	async	When the browser decodes the image.

Example

Paired figures

With src_dark, the figure writes both images and lets the theme choose which one to show. It still carries one accessible identity: the alt text names a wrapper with role="img", and both images are presentational (alt="" and aria-hidden), so assistive technology meets the figure exactly once — in the light, dark, and system themes, in forced colors, under custom CSS, and before the stylesheet loads. The caption and the credit are the figure's own children, outside the wrapper, so they stay readable and a credit link stays operable while its image is hidden.

Notes

• Write alt text that says what the image shows, not that it is an image.
• A decorative image, such as a divider, takes alt="" and no caption; a decorative pair keeps both images decorative and still hides the dark one from assistive technology.
• The two images in src and src_dark should be the same size, so the layout does not jump when the theme changes.