# Images

There are two possible directives for images: the image directive and the figure directive.
Refer to [DocUtils](https://docutils.sourceforge.io/docs/ref/rst/directives.html#images) for more options.

## Image directive

```none
.. image:: images/checkmark.png
    :alt: checkmark
```

Renders the image:

![checkmark](examples/images/checkmark.png)

## Figure directive

The figure directive allows you to use captions.

```none
.. figure:: images/checkmark.png
   :alt: checkmark

   This is the caption for the image
```

Renders the image as:

![checkmark](examples/images/checkmark.png)

## Resize images

You can resize images (and figures) with the option `width`.
When a reader clicks on an image with this option set, the image opens in a popup in full size.
This is handy when images are too small to be read from the documentation page.

For example:

```none
.. figure:: images/diagram.svg
   :width: 150px

.. image:: images/checkmark.png
   :width: 150px
```

Renders the image as:

![image](examples/images/diagram.svg)![image](examples/images/checkmark.png)

Click on the image to preview it in full size.

## Diagrams with metadata

Use the `diagram` directive to wrap a figure or image with metadata so external tools can filter and extract diagrams.
The `:id:` option becomes the wrapper’s HTML `id` attribute.
The remaining options are exposed as `data-*` attributes on the wrapping `<div class="diagram">`.

```none
.. diagram::
   :id: auth-flow
   :tags: networking, security
   :categories: security
   :deployment: core
   :last-reviewed: 2026-06-01

   .. figure:: images/diagram.svg
      :alt: Authentication flow

      Authentication flow diagram.
```

Renders as:

<div class="diagram" id="auth-flow" data-tags="networking,security" data-categories="security" data-deployment="core" data-last-reviewed="2026-06-01">![Authentication flow](examples/images/diagram.svg)</div>