Figure
2 minutes read
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. When it equals src, one image is used in both modes. |
alt |
string | empty | The text alternative. 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
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. - The two images in
srcandsrc_darkshould be the same size, so the layout does not jump when the theme changes.