Installation

Requirements

  • Python 3.10 or later

  • Sphinx 7.0 through 9.x

Install From PyPI

pip install sphinx-lightbox

Install the package into the same Python environment that runs Sphinx.

Install From A Checkout

Install the package into the same Python environment that runs Sphinx:

pip install -e .

This keeps the package importable as lightbox while the project is being developed locally.

Enable the extension

Add lightbox to your Sphinx conf.py:

# If the lightbox package is on sys.path:
extensions = [
    "lightbox",
]

The extension automatically registers its CSS and JavaScript files. No additional template changes are needed.

Image directory setup

The extension works with Sphinx’s standard image pipeline. Place your content images under your source tree, for example:

docs/
├── images/
│   ├── topic-a/
│   │   ├── screenshot-1.png
│   │   └── screenshot-2.png
│   └── topic-b/
│       └── detail.png
└── index.rst

Reference them with standard Sphinx markup. Absolute paths are resolved from the source root:

.. image:: /images/topic-a/screenshot-1.png
   :alt: Topic A screenshot.
   :class: lightbox

Or with document-relative paths:

.. image:: ../images/topic-a/screenshot-1.png
   :alt: Topic A screenshot.
   :class: lightbox

Images are resolved through Sphinx’s collector and placed in _images/ in the HTML build output — not _static/.