sphinxcontrib-images

1.0.1 verified Fri May 01 auth: no python

A Sphinx extension that adds a `.. image-thumbnail::` directive for embedding thumbnail images that link to full-size versions. Current version 1.0.1 (released 2024-11-14), maintained under the sphinx-contrib umbrella. Requires Python >=3.9 and Sphinx >=6.0.

pip install sphinxcontrib-images

Common errors

error WARNING: unknown directive type 'image-thumbnail'. ↓

cause Extension not enabled in conf.py, or extension name typo.

fix

Ensure 'sphinxcontrib.images' is in the extensions list.

error ModuleNotFoundError: No module named 'sphinxcontrib' ↓

cause Package not installed or installed in wrong environment.

fix

Run pip install sphinxcontrib-images and verify with pip list | grep sphinxcontrib.

Warnings

gotcha The extension only works with the HTML builder. Other builders (LaTeX, epub) will ignore or raise errors. ↓

fix Use `if builder.name == 'html':` conditional in conf.py to include only for HTML builds.

gotcha The directive does not support Sphinx's image options like `:align:` or `:class:`. Those are silently ignored. ↓

fix Use raw `.. image::` if you need alignment or classes.

breaking Version 1.0.0 dropped support for Python <3.9 and Sphinx <6.0. Older setups will fail with import errors. ↓

fix Upgrade Python to 3.9+ and Sphinx to 6.0+, or pin to sphinxcontrib-images==0.8.6.

Imports

sphinxcontrib.images
```
from sphinxcontrib.images import ImageThumbnail
```
Direct import of the extension's module is never needed; you add to extensions list.

Quickstart

Add the extension to your Sphinx conf.py, then use the directive in reStructuredText.

# conf.py
extensions = ['sphinxcontrib.images']

# In any .rst file:
# .. image-thumbnail:: path/to/image.png
#    :width: 200px