blueswen/mkdocs-glightbox

A MkDocs plugin supports image lightbox (zoom effect) with GLightbox.

MkDocs GLightbox

A MkDocs plugin supports image lightbox with GLightbox.

GLightbox is a pure javascript lightbox library with mobile support.

Live demo with Material for MkDocs.

Dependency

1. GLightbox javascript file and CSS file
   1. GLightbox==3.2.0

Usage

1. Install the plugin from PyPI

   pip install mkdocs-glightbox

2. Add glightbox plugin to your mkdocs.yml plugins sections:

   plugins:
      - glightbox

3. All images will be added to the lightbox effect automatically, except images in an anchor tag and emoji images from pymdown-extensions.

4. You may customize the plugin by passing options in mkdocs.yml:

   plugins:
      - glightbox:
          touchNavigation: true
          loop: false
          effect: zoom
          slide_effect: slide
          width: 100%
          height: auto
          zoomable: true
          draggable: true
          skip_classes:
            - custom-skip-class-name
          auto_caption: false
          caption_position: bottom
          background: white
          shadow: true
          manual: false

   Option	Default	Description
   touchNavigation	true	Enable or disable the touch navigation (swipe).
   loop	false	Loop slides on end.
   effect	zoom	Name of the effect on lightbox open. (zoom, fade, none)
   slide_effect	slide	Name of the effect on lightbox slide. (slide, zoom, fade, none)
   width	auto	Width for inline elements and iframes. You can use any unit for example 90% or 100vw for full width.
   height	auto	Height for inline elements and iframes. You can use any unit for example 90%, 100vh or auto.
   zoomable	true	Enable or disable zoomable images.
   draggable	true	Enable or disable mouse drag to go prev and next slide.
   skip_classes	[ ]	Disable lightbox of those image with specific custom class name.
   auto_caption	false	Enable or disable using alt of image as caption title automatically.
   caption_position	bottom	Default captions position. (bottom, top, left, right)
   background	white	The background CSS of lightbox image. The background will shown when the image is transparent. You can use any CSS value for the background for example #74b9ff or Gainsboro or none for nothing.
   shadow	true	Enable or disable the shadow of lightbox image. Disable it when the background is none to prevent shadow around the transparent image.
   manual	false	When true, lightbox has to be enabled for each image manually by adding on-glb class to it or adding glightbox: true meta on page.

   Check more options information on GLightbox Docs.

5. For more flexibility:

   1. Disable by image: Disable the lightbox for specific images. Suitable for a few amount of images that don't need the lightbox effect.
   2. Disable by page: Disable the lightbox for specific pages. Suitable for a few amount of pages that don't need the lightbox effect.
   3. Enable by image: Disable the lightbox for specific pages but enable some images on those pages. Suitable for a few amount of images that need the lightbox effect.
   4. Disable globally but enable by image or page: Disable the lightbox globally but enable specific images or specific pages. Suitable for a large number of images or pages that don't need the lightbox effect.

6. Support lightbox image caption, check more details on Caption.

7. Support grouping images as galleries, check more details on Gallery.

Note

If this is your first time using the MkDocs plugin feature, you should know that MkDocs includes a default plugin named search. If you want to keep the search feature, you need to add the search plugin back to the plugins list.

How it works

1. Copy GLightbox script file into site/assets/javascripts/ directory and CSS file into site/assets/stylesheets/ directory
2. Import GLightbox script and CSS file and add javascript code on each page excluded disabled pages
3. Search all image tags and warp with an anchor tag for GLightbox excluded images with skip class or already warped with an anchor tag

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

mkdocs-glightbox's Issues

[Feature request] Group images (gallery)

Hello,

As far as I can see, you can switch between all images on a site, when glightbox is activated.
When you look into https://biati-digital.github.io/glightbox/, then you will see that each gallery have a predefined number of images.

• Simple Image Gallery has 6 images
• Images with Description has 3 images

I do not know how hard it is to implement such a detail, but I think it would be a great extension.
Anyway thank you for this plug-in great work!

Is it possible to make a glightbox inside itself ?

Is is possible to do something like this

![![This is a reason why that solution work](explaination.png)](solution.png)

As there is a case where I have a plugin that automatically takes images of certain explanations into images so that the user can download and view them as a carousel. But I cant not add an image inside another solution, so I have to copy a large amount of text into the solution with a custom plugin.

Also, there is a suggestion, can we have a tooltip when hovering over a image? it shall show data-title inside a rectangle toolip so the user can read the title without enlarging the image (for example: comparing two images title / two different solutions with similar solution)

Social Share?

Is there an easy way to add a "share to [social]" link to the gallery view of images? It would work nicely below the image and before the caption.

Ignore neoteroi-mkdocs elements

Hello,

I'm using neoteroi cards and the glightbox plugin conflicts with the imgs.

Maybe it's currently possible to ignore these imgs but I am not having much success. I think it's because the neoteroi plugin does not allow imgs to have classes bound to them via the input object mechanism

I tried enabling

- glightbox:
      skip_classes: 
        - skip

and applying the skip class to the actual card element to be ignored by glightbox, but glightbox only adheres to img, as it should.

I guess what I'm asking is, is it currently possible to ignore classes of things other than imgs? Right now, I can only get things to work by disabling glightbox on the page completely, which i really don't want to do as it's an awesome plugin.

Enable glightbox don't have search

Hi,

When I active glightbox, don't have a search, please help me how to fix

Thanks.

Global width is ignored

im dumb)

Zoom doesn't work with svg

Hi, not sure if this is supposed to work this way. PNG images open and zoom fine, but SVG images are not zoomable at all. Any solution?

Search bar disappears after adding glightbox as plugin

I'm usig the latest version of Mkdocs-Material.

In my mkdocs.yml file, if I comment out those lines:

# plugins:
#   - glightbox

Then the search bar is displayed and functions well:

However, when I enable it, it disappears:

plugins:
  - glightbox

I have commented out the rest of my mkdocs.yml file and nothing else seems to impact the search bar.
I have also noticed in that it is not here in your live demo either: https://blueswen.github.io/mkdocs-glightbox/

Hopefully it is a quick fix, thanks!

[Feature request] Support switch between themes (typicallly light/dark modes)

Hello,

Nice plugin here, thanks!

Would you consider adding support for color theme and dynamic change?

I see you use the Material for Mkdocs theme for your demao and it's one of its main feature. It would be nice to reuse the colors schemes for the description/title banner :)

Gallery is not loaded in browser after adding plugin and dependencies

Hello, tried to add the plugin and create a gallery, but it does not seem to work.
Even though when inspecting browser I see the JS loads

Dockerfile

FROM squidfunk/mkdocs-material

COPY requirements.txt .

RUN apk add --no-cache gcc musl-dev

RUN pip install -r requirements.txt

Python requirements.txt

mkdocs==1.4.2
mkdocs-awesome-pages-plugin==2.2.1
mkdocs-git-revision-date-localized-plugin==0.5.2
mkdocs-material==5.2.2
mkdocs-material-extensions==1.0
mkdocs-minify-plugin==0.3.0
jinja2==3.0.3
beautifulsoup4>=4.11.1
mkdocs-glightbox

mkdocs.conf

plugins:
  - search
  - awesome-pages
  - minify:
      minify_html: true
  - glightbox:
      touchNavigation: true
      loop: false
      effect: zoom
      slide_effect: slide
      width: 100%
      height: auto
      zoomable: false
      draggable: false
      skip_classes:
        - custom-skip-class-name
      auto_caption: false
      caption_position: bottom

Extra(mkdocs.yml)

extra_javascript:
  - javascripts/glightbox.min.js


extra_css:
  - stylesheets/extra.css
  - stylesheets/glightbox.min.css

The image code in mkdocs the page

![Taipei, Taiwan. Credit: Yuyu Liu](/img/jump.jpg){data-gallery="taipei"}

![Taipei, Taiwan. Credit: Yuyu Liu](/img/pit.jpg){data-gallery="taipei"}

Website to inspect the issue (the last two images in the page)

https://www.rc-drive.com/

Show caption/description in lightbox

Hello,

This is a question but I can't myself label it as so.
I was wondering if the description is shown when the lightbox is open?

With the following

<figure class="image">
  <img src="url" alt="description">
  <figcaption>description</figcaption>
</figure>

Would (Could) the description be shown in full screen view?

Cheers,
M

glightbox is breaking if the privacy plugin is set.

plugins:

  - glightbox:
      touchNavigation: true
      loop: false
      effect: zoom
      slide_effect: slide
      width: 100%
      height: auto
      zoomable: true
      draggable: true
      skip_classes:
        - glightbox-thumb
      auto_caption: false
      caption_position: bottom
      background: white
      shadow: true

  - privacy

it will work if I comment out the privacy bit.

Specifically the error it throws is

Uncaught TypeError: element.querySelector(...) is null
 <anonymous> (index):1066
 <anonymous> (index):1065
 RxJS 7
 No index.ts:44
 RxJS 10
 No index.ts:44
 <anonymous> bundle.ts:133
 <anonymous> bundle.ts:318

The offending code it links to is around here var imgSrc = element.querySelector('img').src;

<script>document$.subscribe(() => {document.querySelectorAll('.glightbox').forEach(function(element) {
    var imgSrc = element.querySelector('img').src;
    element.setAttribute('href', imgSrc);
});
const lightbox = GLightbox({"touchNavigation": true, "loop": false, "zoomable": true, "draggable": true, "openEffect": "zoom", "closeEffect": "zoom", "slideEffect": "slide"});})</script><script>
var livereload = function(epoch, requestId) {
    var req = new XMLHttpRequest();
    req.onloadend = function() {

I'm just going to turn off privacy for now but I wonder why it does that.

Cannot install the plugin with the suggested `pip` command

I cannot install the plugin with the pip install mkdocs-glightbox command as suggested in the README. It appears that pip only displays a warning and the install was successful, but then the plugin is not in the installed package list, and mkdocs cannot find it:

The workaround is to install the plugin with the below command, but it took a while for me to figure this out:

pip install --use-pep517 mkdocs-glightbox

I'm using the following versions:

Consider supporting custom `skip_class` ?

I want to skip custom img tag.

https://github.com/blueswen/mkdocs-glightbox/blob/main/mkdocs_glightbox/plugin.py#L71-L73

Error reading page

when build mkdocs get ERROR - Error reading page 'index.md': 'NoneType' object has no attribute 'group' (v0.4.3)
but in v0.3.2 all good

This version broke my MKDocs from Obsidian

With this update I get "AttributeError: 'NoneType' object has no attribute 'group'" in my deploy to Github Pages

Ignore Shields

After installing glightbox, i noticed when you click on a shield it also opens the image, what breaks the actual action of the shields.

Any way to disable/ignore shields ?

Full parse of each page increases build time twice

As far as I can see, the plugin parses each page of documentation that increase docs build time twice. Is it possible to optimize the plugin work?
Usually, mkdocs built-in plugins use regular expressions to match the specific subsections of documents and then only parse those identified fragments. This is also why the privacy and optimize plugins are very fast, albeit they inspect and alter the HTML output.

Is there a way to set glightbox-manual: true globally?

Hi,
thank you very much for this plugin.

Is there a way to set glightbox-manual: true globally, without the need to include it on every page in the meta?

I would like it always off, and activate it by inserting { .on-glb } where needed.

Thank you

Config value 'plugins': The "glightbox" plugin is not installed after successfully install

Is it possible to define inline elements?

https://biati-digital.github.io/glightbox/#examples has "Iframes and Inline Elements" examples which could be convenient, e.g. for Slideshows.

Is it possible to write Markdown with mkdocs-glightbox which would be rendered as GLightbox inline elements?

Embedding HTML in Markdown files would be fine too.

Responsive image support

glightbox itself supports the data-srcset and data-sizes attributes for responsive images, could you please add support for that?

Check the last example here:
https://github.com/biati-digital/glightbox/blob/master/README.md

Conflict with the privacy plugin of Material theme

This issue is the continuation of this one: squidfunk/mkdocs-material#6248 where you can find every details and a reproducible example.

In a nutshell:

• the Material theme's privacy plugin is meant to avoid requests to external resources
• it can't comply with its promise since mkdocs-ghlightbox use the a[href] to link external image (certainly because of underlying lightbox behavior)

See this comment from @squidfunk:

I've investigated and came to the conclusion that it does not make sense to fix this on our side. Here's why:

Problem

The mkdocs-glightbox plugin currently detects img elements during build time (after the site has been rendered as HTML) and wraps them with a anchor elements. As already noted in #6248 (comment), the privacy plugin only considers assets that are actually rendered to be downloaded. However, the glightbox plugin will wrap the image in an anchor and set href to the image. Normally, an a is a link to an external or internal resource – nothing that is rendered or downloaded without the users consent, thus not under GDPR. This is beyond the scope of the privacy plugin.

Why? Because if we would start downloading resources that are referenced in a[href] attributes, we would need another way to tell the plugin what not to download. Otherwise the plugin will try to download all external resources, which will make configuration much more challenging and the final site will probably blow up in size.

Possible solution

IMHO, there's no need for the glightbox plugin to wrap the img elements during build time – glightbox needs JavaScript to function (open the inspector when you click on an image, and you will see that the JavaScript changes several properties, e.g. on the body). As there's no possibility to make it work without JavaScript (correct me if I'm wrong), I think it's a better idea to defer wrapping of image elements into the browser. The glightbox plugin could just mark elements with a specific class or attribute, e.g. data-glightbox, and provide a small JavaScript that wraps the img elements when the page has loaded. This would mean the correct image would be picked up every time.

This would not only solve the problem at hand, but also be easier to extend to other resources to be presented in the ligtbox, because very soon, the optimize plugin will receive the capability to generate multiple variants of images and wrap them in picture tags. The glightbox plugin could the pick the appropriate source in the picture tag.

If you need help getting this to work, @blueswen, let me know. Wrapping an element in JavaScript is quite simple..

Closing as upstream issue.

Force captions in lightbox to always be white on black

The caption shown in the lightbox seems to inherit the currently selected color scheme. So when the light theme (aka default theme) is selected, the lightbox shows a bright black-on-white caption box which can look unpleasant and distract from the image (esp. when the image is low key). Since the lightbox itself always has a black background, it would make a lot of sense to force the lightbox caption to always have white(ish) text on black background, regardless of currently selected color theme. Is there a way to do so, without modifying the source code?

Add support for mermaid js diagrams

Hi,
Based on squidfunk/mkdocs-material#5208.

Is it possible to add an option to support mermaid js diagrams in the same way as images are supported?

GitHub is also able to display markdown in a way that the mermaid js diagrams become zoomable: https://github.com/squidfunk/mkdocs-material/blob/master/docs/reference/diagrams.md#using-flowcharts

BR

Not able to install glightbox with poetry

Hi there, I just tried to install the glightbox plugin for mkdocs-material (v8.3.9) with poetry, but unfortunately it's not working :-(

Here is what I did:

poetry add mkdocs-glightbox
poetry run mkdocs serve
INFO     -  Building documentation...
ERROR    -  Config value: 'markdown_extensions'. Error: Failed to load extension 'glightbox'.
            ModuleNotFoundError: No module named 'glightbox'
Aborted with 1 Configuration Errors!

The plugin is installed and I can load it:

poetry run python
Python 3.9.13 (main, May 24 2022, 21:28:31) 
[Clang 13.1.6 (clang-1316.0.21.2)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import pkg_resources
>>> named_objects = {}
>>> for ep in pkg_resources.iter_entry_points(group='mkdocs.plugins'):
...     named_objects.update({ep.name: ep.load()})
... 
>>> named_objects['glightbox']
<class 'mkdocs_glightbox.plugin.LightboxPlugin'>
>>>

Strange ...

[Feature Request] Support transparency

Hey, would it feasible to support transparency in in images (e.g on PNGs and SVGs)? Thank you!

Using glightbox stops the default search box appearing

If I add the following to my mkdocs.yml:

plugins:
 - glightbox

...then glightbox works as expected - I can click on images to zoom into them, etc. However, the Search field at the top-right of the page disappears. If I remove those lines, the Search field is back. How can I have glightbox and Search at the same time?

glightbox exponentially slower with increase of the number of images

I have a page with ~50 images and it takes forever to build. Just take some existing project and copy an image directive a lot of times to see for yourself.

I have stopped it in the debugger and it hangs in the regex sub of plugin.py around line 139 where it tries to do all the replacements in one go. I guess the look back/ahead of the regex there degenerates when it sees that many image tags.

maybe using the find_all in regexes and then looping over the matches works better?

PS: I think the re.compile in the function would benefit from being on the class level to only be ever executed once

Error opening images.

When I click on the images, they don't load me correctly, I thought it was where the link was being obtained from but when I open those links, they don't load correctly, could you help me or something, here I put a screenshot what this looks like:

Ignore Emojis

Hi,

first, thanks for your plugin! 👍

When using mkdocs-material with the emoji feature, for example by typing:

Hi :man_raising_hand:

It is also picked up by the lightbox and shown inside the loop, which is quite destroying the user experience.
Is there a way to exclude them?

large image zoom is faulty since 0.3.0

Im using material for mkdocs version 9.1.11 with your plugin, and a large image (for example, 3071 x 1896; 150dpi; 32bit; png) doesn't work well with zoom. On clicking the zoom icon, the picture isn't enlarged. Instead it moves to the left. Sometimes it moves beyond the screen.

I tested with versions 0.2.1, 0.3.0 and the latest, and it only works as it should (zoom icon indeed blows up the image in the browser) in 0.2.1.
Is there an extra configuration option to be set which I am missing since 0.3.0 or is it a bug?

Tested in firefox and chrome.

`glightbox-mkdocs` plugin does not work with `mkdocs-multirepo-plugin`

On its own, I can get the glightbox-mkdocs plugin to work without any issues. My images become 'zoomable' which is the desired effect I am looking for.

However, when I import that same repo with the mkdocs-multirepo-plugin, the 'zoomable' feature of my images in markdown no longer are 'zoomable'.

I installed the glightbox-mkdocs plugin in both my 'parent' multi-repo repo and the child repo, but that did not help.

You can see below that the glightbox script is missing when hosted on Gitlab pages with the mkdocs-multirepo-plugin, but the script is present when hosted on my local workstation via mkdocs serve:

Hosted on Gitlab Pages Using mkdocs-multirepo-plugin

Locally Hosted by running mkdocs serve

Deprecation warning from mkdocs 1.6.0

Hello,

I just wanted to bring to your attention that, with the latest update of mkdocs, your plugin triggers a deprecation warning:

INFO    -  DeprecationWarning: Do not access Theme._vars, instead access the keys of Theme directly.
             File ".../.venv/lib/python3.8/site-packages/mkdocs_glightbox/plugin.py", line 104, in on_post_page
               if self.using_material or "navigation.instant" in config["theme"]._vars.get(
             File ".../.venv/lib/python3.8/site-packages/mkdocs/theme.py", line 87, in _vars
               warnings.warn(

Thanks for the plugin,
Kind regards,
Fred

support `#only-dark` and `#only-light` feature of mkdocs material

This is a very cool plugin!

There is only one problem I am facing, when a page uses the #only-light or #only-dark feature of Mkdocs, the gallery has blank images (for the images which are hidden based on the theme).

For example, if you include the following markdown on a page:

![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa#only-light)
![Image title](https://dummyimage.com/600x400/21222c/d5d7e2#only-dark)

If you are currently in light-mode, the gallery will contain 2 images, with the dark-mode one showing as blank.

[Feature] Add more flexibility

Hi,

it would be great to control the behavior for specific images using the attribute-list syntax in combination with some global options, or even by page using the metadata option.

For example, having the ability to:

• enable the light box globally or by page and disable for specific images
• disable globally or by page and enable for specific images

New version 0.4.0 causes problem with lightbox

Has to revert to older version (0.3.7): vcmi/VCMI.eu#34

Because the lightbox only works for cached images. If you open a uncached page: When you click on image you will see the spinner forever an the image isn't loading.

Now, after revert it's working just fine again.

Web console also generates an error:

Uncaught TypeError: URL constructor:  is not a valid URL.
    Xa index.ts:110
    i index.ts:301
    RxJS 7
12 [index.ts:110:6](https://vcmi.eu/assets/javascripts/src/templates/assets/javascripts/integrations/instant/index.ts)

It seems a href url is unset.

I'm not sure if this bug is coming from this library. Or from https://github.com/squidfunk/mkdocs-material by @squidfunk