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 whole percentage of the text width, to 100 (60%), or a CSS length (5cm). The image is sized to it, scaling up if the file is smaller — supply one at least as wide as it will render. With no width, the image keeps 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. It takes the same values; one it doesn't is dropped with a warning, and the image keeps its natural size.
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. A PDF label
takes only ASCII letters, digits and - : . _; an id with any other character is reported and gets no label.
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, justified, or normal (the surrounding alignment), and the
shortcut still takes width, caption-width, and an #id. This works across every format, including DOCX and ODT.
aligned-figure also takes space-after — trailing space below the figure, as a named size (tiny…huge) or a CSS
length — so a caption need not sit flush against the next paragraph. It defaults to none and is exclusive to
aligned-figure: a plain figure or a bare  gets no trailing space.
::: {.aligned-figure width="40%" space-after="medium"}
:::
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
:::