---
title: "Using images in reST documentation"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:images"
source: "Reference/ReStructuredText/Graphics/Images.rst"
modified: "2026-09-14T09:38:54+00:00"
---

# Using images in reST documentation

You can use the [The example screenshot project](https://docs.typo3.org/permalink/h2document:screenshot-project).
It already follows most of the rules stated below. There has been no automatic
screenshot tool since TYPO3 v11 as it proved to be to complicated to maintain.

> [!WARNING]
> **Attention**
>
> For official and Core manuals please follow the
> [Guidelines for creating images](https://docs.typo3.org/permalink/h2document:guidelines-for-images).

## Images and figures in reST

We recommend to use the `..  figure::` directive. It works just like
`..  image::` save that you can add a descriptive text as content.

Always use the parameter `:alt:` to add a descriptive text for visually impaired
and search engine / artificial intelligence bots scanning our docs.

Example:

**Documentation/MyDocs.rst**

```plaintext
..  figure:: /_Images/a4.jpg
    :alt: some image

    This is the image caption

```

Optional parameters for images and figures:

-   `:target:` link target
-   `:width:` : width of image, use for example px (for example `:width: 100px`
-   `:scale:` : scale images, for example `:scale: 65`
-   `:zoom:` : enable zoom functionality (see [Image zoom and lightbox features](https://docs.typo3.org/permalink/h2document:image-zoom))
-   `:class:` : CSS classes, for example `with-shadow`, `with-border`, `float-left`,
    `float-right` (see [Image and figure floating and alignment](https://docs.typo3.org/permalink/h2document:image-float-alignment))
-   `:align:` : alignment/float for figures: `left`, `right`, `center`
    (see [Image and figure floating and alignment](https://docs.typo3.org/permalink/h2document:image-float-alignment))

Additional parameters can be found on the docutils page [reStructuredText Directives](http://docutils.sourceforge.net/0.4/docs/ref/rst/directives.html#image)

## Example 1: scaled image with shadow and link target

[![Left floating image](../../../_Images/a4.jpg)](https://typo3.org)

```rst
..  figure:: /_Images/a4.jpg
    :alt: some image
    :target: https://typo3.org
    :class: with-shadow
    :scale: 50
```

## Example 2: image with caption and fixed width

![Left floating image](../../../_Images/a4.jpg)

```rst
..  figure:: /_Images/a4.jpg
    :alt: some image
    :width: 100px
    :zoom: lightbox

    This is the image caption
```