Figure

A figure wraps a single image, table, or code block with a caption. The argument is the caption; width accepts a percentage only, because the same source has to typeset to print. In the downgrade the content is followed by the caption in italics.

Give images alt text. The caption describes the figure's role in the document; the alt text describes the image.

Attributes

The argument is the caption and may contain inline markup. Content must be exactly one block: a paragraph holding a single image, a table, or a code block.

Downgrade: the content, followed by the caption as an italic paragraph.

Watch for: width takes percentages only. No pixels and no absolute units, because the same source has to typeset to print, where a pixel means nothing. And when the content is a table the caption is emitted as the table's own <caption> rather than a <figcaption>, because that is the element a screen reader announces as the table's name.

Examples

The argument is the caption and width is a percentage. No pixels, because the same source has to typeset to print.

canonical

Source

:::figure[Request lifecycle from ingress to response]{#fig-lifecycle width=60%}
![](lifecycle.svg)
:::

Rendered

Downgrade

![](lifecycle.svg)

*Request lifecycle from ingress to response*

A figure may wrap a table. The caption is then emitted as the table's own <caption>, which is its accessible name.

:::figure[Sizes]
| a | b |
|---|---|
| 1 | 2 |
:::

| a | b |
| - | - |
| 1 | 2 |

*Sizes*

A code block works too, which is how a listing gets a caption.

:::figure[Listing]
```js
let x = 1;
```
:::

let x = 1;

```js
let x = 1;
```

*Listing*

The caption is inline content, so emphasis, code and links all work inside it.

caption with inline markup

Source

:::figure[The *fast* path]
![](f.svg)
:::

Rendered

Downgrade

![](f.svg)

*The *fast* path*

What the validator catches

Every error below is specified; nothing degrades silently.

:::figure
:::

:::figure
some text
:::

:::figure
![](a.svg) caption here
:::

All 16 cases for figure are in the conformance browser. The normative text is spec §4.