Usage

Two directives are provided by the extension.

Images

Thumbnail

Fullsize

reStructuredText

.. thumb-image:: _images/tux.png
    :resize-width: 100px

Markdown

```{thumb-image} _images/tux.png
:resize-width: 100px
```

.. thumb-image::

Equivalent to the built in image directive. Display a thumbnail image in the document the same way a regular image is displayed. The resized image is written to the Sphinx build working directory doctreedir and copied into the output image directory. If no other image directives reference the fullsize image it won’t be copied into the output directory to save disk space.

align/alt/height/width/scale/target: Same as the image directive. No resizing performed by these options.

:resize-width:: Resize the image into a thumbnail with this width in pixels with the height automatically calculated to maintain the same aspect ratio. Can be an integer or a string such as “100px”. If thumb-image:resize-width and thumb-image:resize-height are both specified the thumbnail will retain its aspect ratio and will be scaled down to fit within both dimensions. A default width may be specified with thumb_image_resize_width in conf.py.

:resize-height:: Resize the image into a thumbnail with this height in pixels with the width automatically calculated to maintain the same aspect ratio. Can be an integer or a string such as “100px”. If thumb-image:resize-width and thumb-image:resize-height are both specified the thumbnail will retain its aspect ratio and will be scaled down to fit within both dimensions. A default width may be specified with thumb_image_resize_width in conf.py.

:target-format:

Boolean option to enable substitutions in the built in :target: option. Built in substitutions:

%(raw_path)s: Replaced with the path to the original fullsize image as given in the directive
%(fullsize_path)s: Replaced with the path to the original fullsize image taking into account subdirectories

Additional substitutions may be provided with the thumb_image_target_format_substitutions option in your conf.py.

Here’s an example for the file docs/posts/2026/guide.rst (conf.py is located at docs/conf.py in this example):

.. thumb-image:: assets/tux.png
    :target: https://cdn/account/docs/%(fullsize_path)s
    :target-format:

The thumbnail image will link to https://cdn/account/docs/posts/2026/assets/tux.png.

:no-target-format:: Boolean option to negate thumb-image:target-format if thumb_image_target_format is True.

Figures

Thumbnail

Fullsize

reStructuredText

.. thumb-figure:: _images/tux.png
    :resize-width: 100px

    This is a thumbnail.

Markdown

```{thumb-figure} _images/tux.png
:resize-width: 100px

This is a thumbnail.
```

.. thumb-figure::: Figures have the same options as the thumb-image directive.

Configuration

Set defaults for the extension in your conf.py file:

thumb_image_resize_width

Default: None

Default width in pixels to use for all thumbnails. Can be an integer or a string such as “100px”. This can be overridden with the thumb-image:resize-width option in the directive in document files. If thumb_image_resize_width and thumb_image_resize_height are both set the thumbnail will retain its aspect ratio and fit within both dimensions.

thumb_image_resize_height

Default: None

Default height in pixels to use for all thumbnails. Can be an integer or a string such as “100px”. This can be overridden with the thumb-image:resize-height option in the directive in document files. If thumb_image_resize_width and thumb_image_resize_height are both set the thumbnail will retain its aspect ratio and fit within both dimensions.

thumb_image_target_format

Default: False

Sets thumb-image:target-format by default for all thumb directives if True.

thumb_image_target_format_substitutions

Default: dict()

Provide additional substitutions with this option. Example:

thumb_image_target_format_substitutions = {"key": "value"}

Will replace %(key)s with value.