{"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":"python","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,"search_vec":"'activ':40 'appli':27 'automat':26 'compat':46 'document':36,54 'effect':30 'enhanc':49 'ensur':45 'featur':48 'frequent':43 'function':24 'galleri':23 'glightbox':2,6,14 'imag':20,32,53 'integr':12 'javascript':16 'librari':18 'lightbox':17,29,52 'maintain':41 'mkdoc':1,5,9,35,50 'mkdocs-glightbox':4 'plugin':3,10,51 'project':38 'pure':15 'updat':44 'within':33 'zoom':21","created_at":"2026-04-12T03:41:39.671411+00:00","updated_at":"2026-04-17T14:41:57.677162+00:00","problems":{"verify_error":"no import statement found"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://blueswen.github.io/mkdocs-glightbox/","github":"https://github.com/blueswen/mkdocs-glightbox","docs":null,"changelog":"https://github.com/blueswen/mkdocs-glightbox/blob/main/CHANGELOG","pypi":"https://pypi.org/project/mkdocs-glightbox/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-05","install_tag":null}}