Using images in ReST documentation

You can use the The example 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.

Attention

For official and Core manuals please follow the Guidelines for creating 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:

..  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)

Additional parameters can be found on the docutils page reStructuredText Directives

Example 1: Scaled image with shadow and link target

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

Example 2: Image with caption and fixed width

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

    This is the image caption

Image zoom and lightbox features

New in version 0.36.0

The image zoom feature was introduced in render-guides version 0.36.0.

The TYPO3 documentation theme provides built-in image zoom and lightbox features to enhance the viewing experience for images and figures. These features allow readers to view images in greater detail without leaving the documentation page.

Available zoom modes

The zoom functionality is controlled by the :zoom: option on figure and image directives. The following zoom modes are available:

lightbox

Click to open the image in a full-screen overlay dialog. The lightbox provides a dark backdrop and centers the image. Click outside the image or press Escape to close. A zoom indicator icon appears on the image.

Use case: Screenshots, diagrams, and any image that benefits from full-screen viewing. This is the recommended mode for most images.

gallery

Click to open the image in a gallery viewer with mouse wheel zoom and navigation between grouped images. Use the :gallery: option to group related images together.

Use case: Series of screenshots, step-by-step tutorials, or image collections that should be navigable together.

inline

Enables scroll wheel zoom directly on the image without opening an overlay. When zoomed, drag to pan. Double-click or press Escape to reset.

Use case: Detailed diagrams or technical drawings that need frequent zoom inspection without leaving context.

lens

A magnifier lens follows the cursor when hovering over the image, showing a zoomed view. A result panel appears beside the image with the magnified area.

Use case: High-resolution images with fine details, such as UI mockups or detailed screenshots.

Directive options

The following options are available for the figure and image directives:

:zoom:: The zoom mode to use. One of: lightbox, gallery, inline, lens.
:gallery:: Group name for gallery mode. Images with the same gallery name can be navigated together. Only used with :zoom: gallery.
:zoom-indicator:: Whether to show the zoom indicator icon. Set to false to hide it. Default is true (shown).
:zoom-factor:: Magnification factor for lens mode. Default is 2. Higher values provide stronger magnification. Only used with :zoom: lens.

Usage examples

Example 3: Lightbox zoom

Example screenshot — Click to open in lightbox. This is the recommended mode for most images.

..  figure:: /_Images/a4.jpg
    :alt: Example screenshot
    :zoom: lightbox
    :class: with-border with-shadow

    Click to open in lightbox.

Example 4: Gallery mode with grouped images

..  figure:: /_Images/step1.png
    :alt: Step 1
    :zoom: gallery
    :gallery: tutorial

    First step of the tutorial.

..  figure:: /_Images/step2.png
    :alt: Step 2
    :zoom: gallery
    :gallery: tutorial

    Second step - navigate with arrow keys.

Example 5: Inline scroll-wheel zoom

..  figure:: /_Images/diagram.png
    :alt: Architecture diagram
    :zoom: inline

    Use scroll wheel to zoom in/out directly on this image.

Example 6: Magnifier lens

..  figure:: /_Images/detailed-ui.png
    :alt: User interface mockup
    :zoom: lens

    Hover over the image to see a magnified view.

Example 7: Hidden zoom indicator

..  figure:: /_Images/screenshot.png
    :alt: Screenshot
    :zoom: lightbox
    :zoom-indicator: false

    Lightbox without visible indicator icon.

Accessibility considerations

All zoom modes are designed with accessibility in mind:

Keyboard navigation

Lightbox and Gallery modes: Full keyboard support
- Tab - Navigate to image and controls
- Enter or Space - Open lightbox/gallery
- Escape - Close lightbox/gallery
- Arrow Left / Arrow Right - Navigate between images (gallery)
- + / - - Zoom in/out (gallery)
Inline zoom mode: Full keyboard support
- Tab - Focus the image
- + / - - Zoom in/out
- Arrow keys - Pan when zoomed
- Escape or 0 - Reset zoom
Lens mode: Keyboard activation supported
- Tab - Focus the image
- Enter or Space - Toggle lens on/off
- Arrow keys - Move lens position
- Escape - Deactivate lens

Reduced motion support

The zoom functionality respects the prefers-reduced-motion media query. When reduced motion is preferred, transitions and animations are disabled.

Best practices

Always include descriptive :alt: text for accessibility
Use lightbox as the default for most images
Use :gallery: to group related images for navigation
Use inline for technical diagrams that need frequent inspection
Combine with :class: with-border with-shadow for better visual presentation
Test zoom functionality with keyboard navigation