---
id: mkdocs-glightbox
version: "0.5.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# mkdocs-glightbox — MkDocs plugin supports image lightbox with GLightbox.

License: permissive · Maintenance: active · Downloads: 1.4M/mo

## What it is and what it does

mkdocs-glightbox is a MkDocs plugin that automatically enhances images in your documentation with an interactive lightbox viewer. When you build your site, the plugin scans all image tags and wraps them with the GLightbox JavaScript library, which provides a modal image viewer with touch navigation, zoom, drag controls, and mobile support. The plugin uses selectolax to parse and modify the HTML.

You control the behavior through mkdocs.yml configuration: enable or disable the lightbox globally, skip specific images by CSS class, customize effects and animations, add captions from image alt text, group images into galleries, and toggle features like zoom and dragging. You can also disable the lightbox for entire pages or enable it selectively on pages where it's otherwise disabled, making it flexible for mixed documentation styles.

Use it for:

- Add interactive image viewing to technical documentation without modifying individual Markdown files
- Create image galleries in your MkDocs site with grouped navigation and swipe controls
- Automatically caption images using their alt text while keeping Markdown source clean
- Disable lightbox for specific images (logos, icons) while enabling it for screenshots and diagrams
- Support mobile documentation viewers with touch-friendly image navigation and zoom

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A MkDocs plugin that automatically wraps images in a lightbox viewer powered by the GLightbox JavaScript library, with support for galleries, captions, and per-image or per-page customization.

Yes. The plugin is production-stable, actively maintained, has low install friction, carries no known vulnerabilities, and solves a common documentation need (interactive images) with minimal configuration. Install it if you use MkDocs and want lightbox functionality without manual HTML editing.

## Install

pip install mkdocs-glightbox
uv add mkdocs-glightbox
poetry add mkdocs-glightbox

## Installing mkdocs-glightbox

Before you install: Low friction install with a single runtime dependency (selectolax). The package is actively maintained with a recent release, marked as Production/Stable, and supports current Python versions from 3.8 through 3.14.

License in practice: MIT license is permissive, allowing free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

pip install mkdocs-glightbox

Then add to mkdocs.yml:
plugins:
  - glightbox

Verify before relying:

- Whether GLightbox JavaScript file version 3.3.1 is automatically bundled or must be manually added to the site
- Specific behavior when images are already wrapped in anchor tags or are emoji from pymdown-extensions

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs image lightbox plugin, glightbox mkdocs integration, image gallery mkdocs, mkdocs image viewer, lightbox effect documentation, mkdocs photo gallery, image modal mkdocs, mkdocs-plugin, image-viewer, documentation-tool

[View on SkillFed](https://skillfed.io/packages/mkdocs-glightbox) · [View on PyPI](https://pypi.org/project/mkdocs-glightbox/)