Skip to main content

MkDocs plugin supports image lightbox with GLightbox.

Project description

MkDocs GLightbox

PyPI version PyPI downloads Codecov

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. Python Package
    1. beautifulsoup4>=4.11.1
  2. 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
    
    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 100% 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)

    Check more options information on GLightbox Docs.

  5. For more flexibility, you can disable the lightbox with a specific image or a specific page.

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

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

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs-glightbox-0.3.2.tar.gz (29.1 kB view hashes)

Uploaded source

Built Distribution

mkdocs_glightbox-0.3.2-py3-none-any.whl (28.6 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page