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

:no-resize:: Does not resize the image and instead just copies it to the output documentation directory. Useful when you want to use the other features in the extension for images that are already small.

:is-animated:: Boolean option that indicates the image is animated (e.g. an animated GIF).

:no-is-animated:: Boolean option to negate thumb-image:is-animated if thumb_image_is_animated is True.

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

Substitutions can also incorporate string slicing:

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

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

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

:no-default-target:: Boolean option to ignore thumb_image_default_target and leave the target unmodified.

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_is_animated

Default: False

Sets thumb-image:is-animated by default for all thumb directives if True.

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.

You can also specify functions or callables as values:

def formatter(self, substitutions, target, env):
    return substitutions["fullsize_path"][2:]
thumb_image_target_format_substitutions = {"key": formatter}

thumb_image_default_target

Default: None

Sets a thumb’s target URL by default for all thumb directives if set to a string. Use this if all thumb images should link to files in the same location, such as an image host or another git repository’s web interface. Supports formatting like thumb-image:target-format.