Figures & images
A plain Markdown image just works — Keystone keeps it where you placed it (rather than letting it float) and takes the caption from the alt text:
The alt text (A lighthouse at dusk.) becomes the caption; an empty alt
() omits the caption. Images go in assets/ and are referenced by
relative path.
Sizing and captions
For control over width and caption behavior, wrap the image in a
figure block:
::: {.figure width="60%"}
:::
width— a CSS length: a percentage of the text width (60%) or an absolute size (5cm). With no width, the image renders at its natural size.caption-width— by default the caption is constrained to the image width; setcaption-width="full"to let it span the full text width (useful under a narrow image).
Width can also ride on the image itself —
{ width=60% } — which is handy for a one-off without the
wrapper.
Cross-references
Give a figure an id with #id (or id=), then link to it from anywhere in the
manuscript:
::: {.figure width="50%" #fig-architecture}
:::
As shown in [the architecture diagram](#fig-architecture), the layers are
independent.
In PDF this produces a label you can reference; in EPUB and HTML it becomes an anchor the link jumps to.
Positioning
A figure has no alignment of its own. To center or left-align one, use the
aligned-figure shortcut, which wraps
the figure in an alignment block:
::: {.aligned-figure align="left" width="40%"}
:::
align accepts center (the default), left, right, or justified, and the
shortcut still takes width, caption-width, and an #id. This works across
every format, including DOCX and ODT.
Reusable presets
If your book uses a few recurring sizes, name them once as shortcuts:
thumbnail:
class: figure
interface:
width:
bind: class.width
default: 25%
::: thumbnail
:::