sphinx-lightbox

sphinx-lightbox is a Sphinx extension that turns standard .. image:: and .. figure:: directives into click-to-enlarge images in HTML output. It uses a CSS checkbox-toggle mechanism, progressively enhanced with a small JavaScript file for keyboard activation, focus management, Escape-to-close, and optional gallery navigation.

Documentation is published at https://aputtu.github.io/sphinx-lightbox/.

Quick Start

pip install sphinx-lightbox

Enable the extension in conf.py:

extensions = ["lightbox"]

Opt a standard image into lightbox behavior:

.. image:: /images/example.png
   :alt: Example image.
   :class: lightbox

Figures are transformed by default and keep their normal page caption:

.. figure:: /images/example.png
   :alt: Example figure.

   This caption is also shown in the lightbox overlay.

Development

Create a local virtual environment and install development dependencies:

make setup

Common commands:

The documentation build writes HTML to docs/_build/html/ and copies the PDF download into docs/_downloads/sphinx-lightbox.pdf before rebuilding HTML, the same pattern used by the GitHub Pages deployment workflow.

Project Layout

sphinx-lightbox/
|-- lightbox/                 Extension package
|   |-- lightbox.py
|   |-- py.typed
|   `-- static/
|       |-- lightbox.css
|       `-- lightbox.js
|-- docs/                     Sphinx documentation source
|   |-- _ext/                 Docs-only validation fixes
|   |-- _templates/           Accessible theme template overrides
|   |-- _downloads/           Generated PDF download location
|   `-- images/               Example images
|-- requirements/             Base, development, and docs requirements
|-- scripts/                  Local development and validation helpers
|-- tests/                    Unit and integration tests
|-- pyproject.toml
|-- tox.ini
`-- Makefile

Requirements

• Python 3.10 or later
• Sphinx 7.0 through 9.x
• LaTeX tooling such as latexmk and texlive-latex-extra for PDF docs
• Java 17 or later, curl, and sha256sum for the optional Nu standards gate

License

GPL-3.0-or-later.