A MkDocs plugin supports image lightbox with GLightbox.
GLightbox is a pure javascript lightbox library with mobile support.
Live demo with Material for MkDocs.
Install the plugin from PyPI
pip install mkdocs-glightbox
Add glightbox
plugin to your mkdocs.yml plugins sections:
plugins:
- glightbox
All images will be added to the lightbox effect automatically, except images in an anchor tag and emoji images from pymdown-extensions.
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.
For more flexibility:
Support lightbox image caption, check more details on Caption.
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 thesearch
plugin back to theplugins
list.
site/assets/javascripts/
directory and CSS file into site/assets/stylesheets/
directoryThis project is licensed under the MIT License - see the LICENSE.md file for details.