Figure

Figures display an image, or other content, with a visible caption below it. The output is an HTML <figure> element with an optional <figcaption>.

Basic syntax

:::figure[Diagram of the water cycle]
![Water cycle](/images/water-cycle.png)
:::

→ The image appears inside a <figure> element with "Diagram of the water cycle" as the caption below it.

Without a caption

Omit the caption text to render a <figure> without a <figcaption>:

:::figure[]
![Lab equipment](/images/lab-setup.jpg)
:::

→ The image renders inside a <figure> container with no caption. This is useful when the semantic <figure> wrapper is needed for styling but no visible text is appropriate.

Rich content

Figures can contain any Markdown content, not only images. Use them to caption code blocks, tables, or diagrams:

:::figure[Student enrollment by department, 2024]
| Department | Students |
|------------|----------|
| Biology | 142 |
| Chemistry | 98 |
| Physics | 76 |
:::

→ A table appears inside a <figure> with the caption "Student enrollment by department, 2024" below it.

Options

Edge cases

• The caption is required in the syntax (square brackets must be present), but the text inside can be empty.
• The caption text is HTML-escaped. Markdown formatting inside the caption is not rendered.
• Figures can nest other block extensions. Close the figure with :::/figure when nesting.
• Multiple images inside a single figure share the same caption.