5 Apr 2026

Thumbnails¶

Sphinx allows you to specify height, width and scale for images and figures. Additionally, you can set the size of images in the Infoboxes directive. However, Sphinx does not resize the images to appropriate sizes on it’s own.

To solve that, we have implemented a simple thumbnailing mechanism which makes (modern) browsers display scaled-down versions of images, if it is possible to do so without quality loss.

Configuration¶

This functionality is disabled by default and can be enabled like so:

conf.py¶

mcl_extras_use_thumbnails = True

Sphinx allows setting widths and heights in CSS units too. For thumbnailing to work size of image in CSS pixels will have to be known at build time. As such, only the images with their dimensions in following units will be processed:

None (no unit, just number that represents pixels)
px Pixels
pt Points

And, if enabled:

rem and em

rem and em are enabled by default and assumed to be 16 pixels wide. You can change that in configuration as well:

conf.py¶

mcl_extras_thumbnails_em_size = 32
mcl_extras_thumbnails_rem_size = 32

Support for those units can be disabled by setting their size to None:

conf.py¶

mcl_extras_thumbnails_em_size = None
mcl_extras_thumbnails_rem_size = None

Also, since CSS pixels are not actual screen pixels, thumbnailing mechanism renders thumbnails at three different DPRs (device pixel ratios): 1 (desktops), 2 (Retina displays, TVs etc), 3 (HiDPI mobile phones). You can also change that in configuration:

conf.py¶

# Default value:
mcl_extras_thumbnails_dpr_sizes = [1, 2, 3]

Demo¶

The thumbnails are actually enabled for this documentation, so check out the following pages to see how they work (look for srcset attribute):