MkDocs GLightbox

MkDocs插件，支持使用GLightbox的图片灯箱。

GLightbox是一个支持移动端的纯JavaScript灯箱库。

在线演示，配合MkDocs Material使用。

依赖

1. GLightbox JavaScript文件和CSS文件
   1. GLightbox==3.2.0

用法

1. 从PyPI安装插件

   pip install mkdocs-glightbox
   

2. 将glightbox插件添加到mkdocs.yml的插件部分

   plugins:
      - glightbox
   

3. 所有图片都将自动添加到灯箱效果中，除了锚点标签中的图片和来自pymdown-extensions的emoji图片。

4. 您可以通过在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
   

   选项	默认值	描述
   touchNavigation	true	启用或禁用触摸导航（滑动）。
   loop	false	在结束时循环幻灯片。
   effect	zoom	灯箱打开时的效果名称。（放大，淡入，无）
   slide_effect	slide	灯箱幻灯片时的效果名称。（滑动，放大，淡入，无）
   width	auto	内联元素和iframe的宽度。您可以使用任何单位，例如90%或100vw以实现全宽。
   height	auto	内联元素和iframe的高度。您可以使用任何单位，例如90%，100vh或auto。
   zoomable	true	启用或禁用可缩放图片。
   draggable	true	启用或禁用鼠标拖动以切换前一张和下一张幻灯片。
   skip_classes	[ ]	禁用具有特定自定义类名的图片的灯箱。
   auto_caption	false	启用或禁用自动使用图片的alt作为标题。
   caption_position	bottom	默认标题位置。（底部，顶部，左侧，右侧）
   background	白色	灯箱图片的背景CSS。当图片透明时，将显示背景。您可以为背景使用任何CSS值，例如 #74b9ff 或 Gainsboro 或 none 表示无。
   阴影	true	启用或禁用灯箱图片的阴影。当背景为 none 时禁用，以防止透明图片周围出现阴影。
   手动	false	当为true时，必须手动为每个图片启用灯箱，方法是将 on-glb 类添加到其中或添加页面上的 glightbox: true 元数据。

   更多选项信息请参阅 GLightbox 文档。

5. 更多灵活性

   1. 按图片禁用：禁用特定图片的灯箱。适用于少量不需要灯箱效果的图片。
   2. 按页面禁用：禁用特定页面的灯箱。适用于少量不需要灯箱效果的页面。
   3. 按图片启用：禁用特定页面的灯箱，但启用这些页面上的某些图片。适用于少量需要灯箱效果的图片。
   4. 全局禁用但按图片或页面启用：全局禁用灯箱，但启用特定图片或特定页面。适用于大量不需要灯箱效果的图片或页面。

6. 支持灯箱图片标题，更多详情请参阅 标题。

7. 支持将图片分组为相册，更多详情请参阅 相册。

[!NOTE] 如果您是第一次使用MkDocs插件功能，您应该知道MkDocs包含一个名为 search 的默认插件。如果您想保留搜索功能，则需要将 search 插件添加回 plugins 列表。

工作原理

1. 将GLightbox脚本文件复制到 site/assets/javascripts/ 目录，将CSS文件复制到 site/assets/stylesheets/ 目录
2. 导入GLightbox脚本和CSS文件，并将javascript代码添加到每个页面（除禁用页面外）
3. 搜索所有图片标签，并用锚点标签包裹GLightbox，排除带有skip类的图片或已用锚点标签包裹的图片

许可

本项目采用MIT许可 - 有关详细信息，请参阅 LICENSE.md 文件。