{"id":4116,"library":"mkdocs-glightbox","title":"MkDocs GLightbox Plugin","description":"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.","status":"active","version":"0.5.2","language":"en","source_language":"en","source_url":"https://github.com/blueswen/mkdocs-glightbox","tags":["mkdocs","plugin","lightbox","image","documentation"],"install":[{"cmd":"pip install mkdocs-glightbox","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Used for efficient HTML parsing and manipulation.","package":"selectolax","optional":false}],"imports":[{"note":"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.","wrong":"from mkdocs_glightbox.plugin import LightboxPlugin # Not a direct Python import for user code","symbol":"glightbox","correct":"plugins:\n  - glightbox"}],"quickstart":{"code":"mkdocs.yml:\n```yaml\nsite_name: My Docs with Lightbox\ntheme: material # Or any other MkDocs theme\n\nplugins:\n  - search # Keep default search if desired\n  - glightbox:\n      touchNavigation: true\n      loop: false\n      effect: zoom\n      auto_caption: true\n```\n\ndocs/index.md:\n```markdown\n# Welcome\n\nThis is an image with a lightbox effect:\n\n![A descriptive alt text for the image](img/example.jpg)\n\nThis is another image, part of a gallery:\n\n![Another image](img/another.png){ data-gallery=\"my-gallery\" }\n\n```","lang":"yaml","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Modify your `mkdocs.yml` to include `search` like this:\n```yaml\nplugins:\n  - search\n  - glightbox\n```","message":"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`.","severity":"gotcha","affected_versions":"All versions (MkDocs behavior)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.5.1, 0.5.2"},{"fix":"To restore the previous behavior, add `width: 100%` to your `glightbox` plugin configuration in `mkdocs.yml`:\n```yaml\nplugins:\n  - glightbox:\n      width: 100%\n```","message":"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.","severity":"gotcha","affected_versions":">=0.3.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.4.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}