MkDocs GLightbox Plugin

0.5.2 · active · verified Sat Apr 11

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.

Warnings

breaking Version 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.
Fix: Ensure your environment has `selectolax>=0.3.29` installed. If you had custom HTML parsing, adapt it to use `selectolax` if direct interaction with the parsing backend was expected.
gotcha When 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`.
Fix: Modify your `mkdocs.yml` to include `search` like this: ```yaml plugins: - search - glightbox ```
gotcha Between 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.
Fix: If encountering installation issues, ensure your Python version is compatible and consider explicitly installing a known working `selectolax` version if problems persist. Upgrading `mkdocs-glightbox` to the latest version should resolve many dependency-related issues.
gotcha The 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.
Fix: To restore the previous behavior, add `width: 100%` to your `glightbox` plugin configuration in `mkdocs.yml`: ```yaml plugins: - glightbox: width: 100% ```
gotcha Version 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.
Fix: If you enabled `manual: true`, explicitly add `on-glb` to images (e.g., `![alt](img.jpg){ .on-glb }`) or add `glightbox: true` to page metadata to enable the lightbox. Otherwise, ensure `manual` is set to `false` or omitted for automatic behavior.

Install

pip install mkdocs-glightbox Install from PyPI

Imports

glightbox
```
plugins:
  - glightbox
```
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.

Quickstart

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" }

```

view raw JSON →