mkdocs-glightbox

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 on this page — 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

mkdocs-glightbox on PyPI

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

Evidence: mkdocs_glightbox-0.5.2-py3-none-any.whl

Keywords: glightbox, mkdocs, plugin

Tags

More Text Processing packages