Registry / web-framework / mkdocs-glightbox

mkdocs-glightbox

library0.5.2pypypiunverified

mkdocs-glightbox is an MkDocs plugin that integrates the GLightbox pure JavaScript lightbox library for image zooming and gallery functionality. It automatically applies a lightbox effect to images within your MkDocs documentation. The project is actively maintained with frequent updates, ensuring compatibility and feature enhancements.

web-framework

github ↗package ↗homepage ↗changelog ↗

Install & Compatibility

Where this runs

tested against v0.5.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 31.2MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.8s · import 0.000s · 32MB

29MB installed

● package 29MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MkDocs plugins are configured in mkdocs.yml, not directly imported in Python user code. Add 'glightbox' to the 'plugins' section of your mkdocs.yml file to enable it.

plugins: - glightbox

To quickly get started, install the plugin and then enable it in your `mkdocs.yml` file under the `plugins` section. By default, it will automatically apply a lightbox effect to all images. For more advanced features like galleries, use the `data-gallery` attribute in your Markdown. Remember to explicitly list other desired plugins (like `search`) if you define a `plugins` section.

mkdocs.yml: ```yaml site_name: My Docs with Lightbox theme: material # Or any other MkDocs theme plugins: - search # Keep default search if desired - glightbox: touchNavigation: true loop: false effect: zoom auto_caption: true ``` docs/index.md: ```markdown # Welcome This is an image with a lightbox effect: ![A descriptive alt text for the image](img/example.jpg) This is another image, part of a gallery: ![Another image](img/another.png){ data-gallery="my-gallery" } ```

Debug

Known footguns

breakingVersion 0.5.0 replaced the `regex` library with `selectolax` for HTML processing. While this improves performance and maintainability, any projects that previously relied on `regex` as an indirect dependency or had custom logic tied to its behavior might experience breakage.

gotchaWhen defining the `plugins` section in `mkdocs.yml`, MkDocs will override its default `search` plugin. To retain the search functionality, you must explicitly add `search` back to the `plugins` list alongside `glightbox`.

gotchaBetween versions 0.5.1 and 0.5.2, the `selectolax` dependency was initially pinned to `0.3.29` (to avoid missing binary wheel issues) and then updated to `>=0.3.29` to support Python 3.14. This indicates potential sensitivity to `selectolax` versions, especially in specific Python environments.

gotchaThe default `width` option for the lightbox changed from `100%` to `auto` in version 0.3.6 to prevent a bug with zooming large images. If you rely on images filling the full width of the lightbox by default, you might need to explicitly set `width: 100%` in your configuration.

gotchaVersion 0.4.0 introduced 'manual mode', allowing users to opt-in to the lightbox effect for specific images or pages. If `manual: true` is configured, images will no longer automatically have the lightbox effect unless they have the `on-glb` class or the page has `glightbox: true` metadata.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

71 hits · last 30 days

chatgpt-user

petalbot

bytedance

baidubot