In Markdown, an image on its own line renders as a block-level image — but it has no caption, no label, and no way to refer to it from elsewhere in your document. A figure wraps one or more images (or other content) and adds:

Use a plain block image when you just want to show a picture. Use a figure when the image is a first-class part of your document that readers need to identify and reference.

A figure in Stencila Markdown starts with a colon fence line with the keyword figure and optional label, layout, and padding. In a basic figure there is usually a single image and a caption paragraph.

Every figure automatically receives a sequential label — "Figure 1", "Figure 2", and so on — based on its position in the document. You do not need to manage these numbers yourself; if you reorder figures, the labels update to match.

You can set an explicit label by placing it after the figure keyword. However, it is almost always better to omit explicit labels and let Stencila assign them automatically. Explicit labels do not update when you rearrange your document and can easily get out of sync.

Every figure automatically receives an id derived from its label with a fig- prefix — a figure labelled "1" gets fig-1, a subfigure labelled "1A" gets fig-1a. You can link to any figure using a standard Markdown link with a # target:

Auto-derived IDs like fig-1 change whenever you add, remove, or reorder figures. For figures that are referenced from other documents, external links, or APIs, you can assign a stable ID with #<id> on the fence line:

This figure is always reachable at #specimen-1 regardless of its position in the document.

Inside a ::: figure fence, Stencila separates content from caption automatically:

The caption can appear before or after the image — Stencila treats it the same way. Both of these produce identical output:

You can include multiple paragraphs in the caption:

Figures are not limited to images loaded from local files or remote URLs. They can also contain visual output generated by executable code blocks, which makes them useful for reproducible charts, plots, and other computed graphics.

This is especially helpful when the figure should stay in sync with the data or analysis in your document. The executable code generates the figure content, and the surrounding figure still provides the usual captioning, numbering, and cross-referencing. The example below uses Plotly JSON because it is lightweight and built in to Stencila, but the same pattern can be used with figures generated from Python, R, or other supported execution kernels.

A figure can contain nested figures as subfigures. Each subfigure gets its own sub-label (A, B, C, …) and optional caption, while the parent figure holds the overall caption.

To arrange subfigures in a grid, add a layout specification in square brackets after figure:

The layout mini-language is designed to make simple layouts easy to write while keeping more complex arrangements possible. Rather than requiring full CSS, it provides a compact shorthand that covers the most common multi-panel figure patterns.

The keyword row places all subfigures side-by-side in a single row without having to count them:

A single integer specifies the number of equal-width columns. Subfigures flow left-to-right, top-to-bottom:

Space-separated integers define proportional column widths. The numbers are relative — 30 70 means a 30:70 split:

Add a gap between columns using the gN token. For example, 40 g20 40 means two columns of equal width with a gap between them:

For precise control over where each subfigure appears, use a layout map. Letters represent subfigures (a = first subfigure, b = second, etc.), spaces separate columns, and pipes (|) separate rows:

Repeating a letter across rows makes that subfigure span vertically:

Repeating a letter across columns makes that subfigure span horizontally:

Use . to leave a cell empty:

For layouts that need both unequal column widths and precise placement, put the column specification before a : and the layout map after it:

Subfigure images do not need to share the same aspect ratio. When images in the same row have different heights, each image preserves its natural proportions and is vertically centered within the row:

An overlay is a transparent SVG layer rendered on top of a figure's visual content. Use overlays to add annotations — circles, arrows, bounding boxes, text labels — without modifying the underlying image.

Because each overlay is attached to a specific figure or subfigure and uses SVG viewBox scaling, annotations stay locked to the content they describe regardless of how the page is displayed. On a wide desktop screen a two-column layout renders side by side with each panel's overlay covering exactly that panel; on a narrow mobile screen the same grid collapses to a vertical stack and the overlays scale down with their panels, keeping every circle, arrow, and label in the right place. This means you author annotations once and they work everywhere — web, mobile, print, and PDF — without any manual adjustment.

Inside a ::: figure fence, add a fenced code block with the info string svg overlay containing an <svg> element. The SVG viewBox defines the coordinate system used for your annotations. Matching the dimensions of the underlying content is often the simplest option because coordinates then map directly to image or chart pixels, but it is not required: you can use any viewBox that is convenient, such as 0 0 1000 1000, as long as you author the annotation geometry in that same coordinate space.

Overlay shapes and text inherit theme defaults — stroke color, stroke width, fill, font family, font size, and font weight — from the --figure-overlay-* design tokens. In common cases you only need to specify geometry; when you need a specific color, weight, dash pattern, or other non-default treatment on an element, set it explicitly as an inline SVG attribute and it will take precedence over the theme default.

The examples below use overlay components — high-level elements like <s:callout>, <s:arrow>, <s:scale-bar>, and <s:roi-rect> that expand to standard SVG during compilation. Components handle arrowhead definitions, label positioning, and coordinate math automatically. You can also write raw SVG directly; see the overlay components reference for the full component catalog and details on mixing components with raw SVG.

A single annotation overlay on a figure. Here the viewBox="0 0 600 300" matches the 600×300 placeholder image, so coordinates map directly to pixel positions. This direct mapping is convenient for static images, but it is just a convention rather than a requirement — you can use any viewBox that suits your needs:

Overlays also work on figures whose visual content is generated by executable code. As with image-based figures, the SVG viewBox can use any coordinate system you prefer. Matching the dimensions of the rendered output is often the easiest approach because it lets you reason in output pixels and tends to be the clearest choice when aligning annotations with a chart or plot.

This example uses color-coded <s:callout> components with curved leader lines to annotate an R histogram. Each callout uses an explicit fill to distinguish the annotations:

Overlays also work with browser-side rendering libraries like Plotly, eCharts, and Vega-Lite. However, because these libraries can resize their output dynamically (for example, to fill a container or respond to a window resize), overlay alignment is currently most reliable when you set explicit width and height in the chart's layout options and use a matching SVG viewBox. This is a practical workaround for dynamically sized chart output, not a general requirement of SVG overlays.

Each subfigure can carry its own overlay. The overlay on each panel is scoped to that subfigure's content area. Here an <s:roi-rect> highlights a rectangular region on the left panel and an <s:roi-ellipse> highlights an elliptical region on the right:

A top-level figure with subfigures can also carry its own overlay. Because this overlay sits above the entire grid, it can annotate relationships between panels — for example, drawing an arrow from a feature in one subfigure to a corresponding feature in another. Each subfigure can still have its own overlay alongside the parent one.

On small screens the grid collapses to a vertical stack, and when that happens the parent overlay is automatically hidden. The grid layout that the overlay was designed for no longer exists, so its coordinates would be meaningless. Subfigure overlays are unaffected — each one is scoped to its own panel and continues to scale correctly.

In this example the parent overlay draws a connecting <s:arrow> between the two panels, while each subfigure uses its own overlay — a <s:halo> with <s:callout> on the left and an <s:roi-rect> on the right. The parent overlay uses figure-level coordinates rather than either panel's local pixel coordinates, so its viewBox describes the overall two-panel layout rather than the dimensions of an individual image:

Padding adds whitespace around a figure's content area. For overlays, that extra space becomes part of the overlay coordinate space, which lets you place arrows, labels, notes, or scale bars just outside the image instead of drawing over it.

Add padding on the figure fence using a pad attribute:

When using more than one padding value, quote the value so it is parsed as a single attribute.

Padding extends the overlay coordinate space. For an image that is W×H pixels with pad="T R B L", the overlay viewBox should be "0 0 (W+L+R) (H+T+B)" and the image top-left sits at coordinate (L, T). This means all image-space coordinates shift right by L and down by T.

When top and left padding are both zero (the most common case — adding space below or to the right), image coordinates do not change. For example, {pad="0 0 56 0"} on a 600×300 image gives viewBox="0 0 600 356" and the image still starts at (0, 0). But {pad="50 20 56 20"} on the same image gives viewBox="0 0 640 406" with the image top-left at (20, 50), so an annotation that was at x="100" y="80" in the unpadded image needs to move to x="120" y="130".

This example adds bottom padding so a <s:scale-bar> can sit below the image instead of covering it:

Padding also works on parent figures with grid layouts. Here the parent figure uses bottom padding so <s:callout> leader lines can point into each panel from a shared label below the grid: