TeachBooks Zoomies

A simple Sphinx extension to integrate Viewer.js for image zooming in Jupyter Books and Sphinx documentation.

Features

• Pinch & Zoom: Smooth, mobile-friendly zooming for all your images.
• Theme Integrated: Automatically adapts to light and dark modes, using your theme's native colors.
• Smart Captions: Automatically pulls captions from <figure> elements to display them in the viewer.
• Best-Fit Logic: Intelligently scales images to fit your viewport (configurable).
• Customizable Toolbar: Choose exactly which tools (zoom, rotate, reset) are available to your readers.

Installation

pip install teachbooks-zoomies

Usage

Jupyter Book

Add the extension to your _config.yml:

sphinx:
  extra_extensions:
    - teachbooks_zoomies

Sphinx

Add the extension to your conf.py:

extensions = [
    # ...
    'teachbooks_zoomies',
]

Configuration

TeachBooks Zoomies works out-of-the-box with PyData-based themes (like the Jupyter Book default), but you can fully customize it in your _config.yml (Jupyter Book) or conf.py (Sphinx).

Options

Example _config.yml (Jupyter Book)

sphinx:
  config:
    zoomies_selector: ".bd-article img, #pst-secondary-sidebar img, .my-custom-image-class"
    zoomies_best_fit: 85
    zoomies_toolbar: ["zoomIn", "zoomOut", "reset", "rotateRight"]

Example conf.py (Sphinx)

zoomies_selector = ".bd-article img, #pst-secondary-sidebar img"
zoomies_best_fit = 80

Disabling Zoom for Specific Images

If you want to prevent specific images from being zoomable, you can add the class no-zoomies to the image itself or to any of its parent containers.

1. In Markdown (MyST Directive)

This is the recommended way for Jupyter Books.

```{image} path/to/image.png
:class: no-zoomies
```

2. Using an HTML Tag

If you are writing raw HTML in your documentation.

<img src="path/to/image.png" class="no-zoomies">

3. Using a Parent Container

Useful for disabling zoom on a group of images at once.

<div class="no-zoomies">
  ![This image won't zoom](image1.png)
  ![This one won't either](image2.png)
</div>