JB1 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).
• Dark Mode Optimization: Option to automatically invert image colors in dark mode—perfect for scientific plots with white backgrounds.
• Customizable Toolbar: Choose exactly which tools (zoom, rotate, reset) are available to your readers.

Installation

pip install jb1-zoomies

Or from source:

pip install .

Usage

Jupyter Book

Add the extension to your _config.yml:

sphinx:
  extra_extensions:
    - jb1_zoomies

Sphinx

Add the extension to your conf.py:

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

Configuration

JB1 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, .my-custom-image-class"
    zoomies_best_fit: 85
    zoomies_toolbar: ["zoomIn", "zoomOut", "reset", "rotateRight"]
    zoomies_invert_colors: false  # Disable if your images are already dark-mode friendly

Example conf.py (Sphinx)

zoomies_selector = ".bd-article img"
zoomies_best_fit = 80
zoomies_invert_colors = True