Add manual mode

blueswen · blueswen · commit 1409b0de89bd · 2024-05-06T22:29:20.000+08:00
diff --git a/demo-mkdocs/docs/flexibility/disable-by-image.md b/demo-mkdocs/docs/flexibility/disable-by-image.md
diff --git a/demo-mkdocs/docs/flexibility/disable-by-page-enable-by-image.md b/demo-mkdocs/docs/flexibility/disable-by-page-enable-by-image.md
diff --git a/demo-mkdocs/docs/flexibility/disable-by-page.md b/demo-mkdocs/docs/flexibility/disable-by-page.md
diff --git a/demo-mkdocs/docs/flexibility/enable-by-image-or-page.md b/demo-mkdocs/docs/flexibility/enable-by-image-or-page.md
@@ -0,0 +1,118 @@
+You can keep the whole site's images without lightbox effect but only enable lightbox effect on specific images or images on specific pages with the `manual` plugin option.
+
+```yaml
+plugins:
+  - glightbox:
+      manual: true # enable manual mode, all images will not be added to the lightbox effect
+```
+
+## Enable specific images
+
+Enable lightbox effect on specific images by adding `on-glb` class to the image through markdown_extensions ```attr_list```. Enable ```attr_list``` via ```mkdocs.yml```:
+
+```yaml
+markdown_extensions:
+  - attr_list
+```
+
+Check more details about ```attr_list``` on the [official document](https://python-markdown.github.io/extensions/attr_list/).
+
+### Demo
+
+Only images with ```on-glb``` class will be added to the lightbox effect. Other images on the site will not be added to the lightbox effect.
+
+```yaml
+# mkdocs.yml
+markdown_extensions:
+  - attr_list
+
+plugins:
+  - glightbox:
+      manual: true
+```
+
+```markdown
+
+![Lanyu, Taiwan](../images/gallery/blueswen-lanyu.jpeg){ .on-glb } 
+Lanyu, Taiwan. Credit: Blueswen
+
+![Hallstatt, Austria](../images/gallery/blueswen-hallstatt.jpeg){ .on-glb } 
+Hallstatt, Austria. Credit: Blueswen
+
+![Madeira, Portugal](../images/gallery/blueswen-madeira.jpeg)
+Madeira, Portugal. Credit: Blueswen
+
+```
+
+<figure markdown>
+
+![Lanyu, Taiwan](../images/gallery/blueswen-lanyu.jpeg)
+
+<figcaption>Lanyu, Taiwan. Credit: Blueswen</figcaption>
+</figure>
+
+<figure markdown>
+
+![Hallstatt, Austria](../images/gallery/blueswen-hallstatt.jpeg)
+
+<figcaption>Hallstatt, Austria. Credit: Blueswen</figcaption>
+</figure>
+
+<figure markdown>
+
+![Madeira, Portugal](../images/gallery/blueswen-madeira.jpeg){ .off-glb }
+
+<figcaption>Madeira, Portugal. Credit: Blueswen</figcaption>
+</figure>
+
+## Enable specific pages
+
+Enable lightbox effect on specific pages, add page metadata ```glightbox: true``` through markdown_extensions ```meta```. Enable ```meta``` via ```mkdocs.yml```:
+
+```yaml
+markdown_extensions:
+  - meta
+```
+
+Check more details about ```meta``` on the [official document](https://python-markdown.github.io/extensions/meta_data/).
+
+### Demo
+
+Only pages with `glightbox: true` meta will be added to the lightbox effect. Other images on the site will not be added to the lightbox effect.
+
+```yaml
+# mkdocs.yml
+markdown_extensions:
+  - meta
+
+plugins:
+  - glightbox:
+      manual: true
+```
+
+```markdown
+---
+glightbox: true
+---
+
+![Castelo de São Jorge, Lisbon, Portugal](../images/gallery/blueswen-lisbon.jpeg)
+Cabo da Roca, Portugal. Credit: Blueswen
+
+![Yosemite, USA.](../images/gallery/blueswen-yosemite.jpeg)
+Yosemite, USA. Credit: Blueswen
+
+```
+
+<figure markdown>
+
+![Castelo de São Jorge, Lisbon, Portugal](../images/gallery/blueswen-lisbon.jpeg)
+
+<figcaption>Cabo da Roca, Portugal. Credit: Blueswen</figcaption>
+</figure>
+
+<figure markdown>
+
+![Yosemite, USA.](../images/gallery/blueswen-yosemite.jpeg)
+
+<figcaption>Yosemite, USA. Credit: Blueswen</figcaption>
+</figure>
diff --git a/demo-mkdocs/docs/index.md b/demo-mkdocs/docs/index.md
@@ -69,13 +69,17 @@ GLightbox is a pure javascript lightbox library with mobile support.
     | 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. |
+    | 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](https://github.com/biati-digital/glightbox#lightbox-options).
 
-5. For more flexibility, you can disable the lightbox with a [specific image](./disable/image.md) or a [specific page](./disable/page.md).
-6. Support lightbox image caption, check more details on [Caption](./caption/caption.md).
-7. Support grouping images as galleries, check more details on [Gallery](./gallery/gallery.md).
+5. For more flexibility:
+      1. [Disable by image](./flexibility/disable-by-image.md): Disable the lightbox for specific images. Suitable for a few amount of images that don't need the lightbox effect.
+      2. [Disable by page](./flexibility/disable-by-page.md): Disable the lightbox for specific pages. Suitable for a few amount of pages that don't need the lightbox effect.
+      3. [Enable by image](./flexibility/disable-by-page-enable-by-image.md): 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](./flexibility/enable-by-image-or-page.md): 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](./caption/caption.md).
+7.  Support grouping images as galleries, check more details on [Gallery](./gallery/gallery.md).
 
 !!! note
 
diff --git a/demo-mkdocs/mkdocs.yml b/demo-mkdocs/mkdocs.yml
@@ -69,6 +69,7 @@ nav:
   - Caption: caption/caption.md
   - Gallery: gallery/gallery.md
   - More Flexibility:
-    - Disable by image: disable/image.md
-    - Disable by page: disable/page.md
-    - Enable by image: disable/manual.md
+    - Disable by image: flexibility/disable-by-image.md
+    - Disable by page: flexibility/disable-by-page.md
+    - Enable by image: flexibility/disable-by-page-enable-by-image.md
+    - Disable globally but enable by image or page: flexibility/enable-by-image-or-page.md
diff --git a/mkdocs_glightbox/plugin.py b/mkdocs_glightbox/plugin.py
@@ -157,12 +157,19 @@ def wrap_img_with_anchor(self, match, plugin_config, skip_class, meta):
             classes = re.findall(r'class="([^"]+)"', img_attr)
             classes = [c for match in classes for c in match.split()]
 
-            if meta.get("glightbox-manual", False) or self.config["manual"]:
-                if "on-glb" not in classes:
-                    return img_tag
-            else:
+            if self.config["manual"] and meta.get("glightbox", None) is True:
+                # with manual mode but enable glightbox in page meta
                 if set(skip_class) & set(classes):
+                    # skip image with off-glb and specific class
+                    return img_tag
+            elif meta.get("glightbox-manual", False) or self.config["manual"]:
+                # disable by page meta or global config
+                if "on-glb" not in classes:
+                    # skip image without on-glb class
                     return img_tag
+            elif set(skip_class) & set(classes):
+                # skip image with off-glb and specific class
+                return img_tag
 
             if self.using_material_privacy:
                 # skip href attribute if using material privacy plugin, will be set by js code
diff --git a/tests/fixtures/docs/manual_enable_by_page.md b/tests/fixtures/docs/manual_enable_by_page.md
@@ -0,0 +1,9 @@
+---
+glightbox: true
+---
+
+![image-a](img.png)
+
+![image-b](img.png){ .off-glb }
+
+![image-c](img.png)
diff --git a/tests/fixtures/mkdocs-material-instant.yml b/tests/fixtures/mkdocs-material-instant.yml
@@ -0,0 +1,14 @@
+site_name: test mkdocs_glightbox
+use_directory_urls: true
+
+theme:
+  name: material
+  features:
+    - navigation.instant
+
+markdown_extensions:
+  - attr_list
+  - md_in_html
+
+plugins:
+    - glightbox
diff --git a/tests/test_builds.py b/tests/test_builds.py
@@ -192,6 +192,26 @@ def test_material(tmp_path):
     )
 
 
+def test_material_instant(tmp_path):
+    """
+    Integrate with Material for MkDocs
+    """
+    mkdocs_file = "mkdocs-material-instant.yml"
+    testproject_path = validate_mkdocs_file(tmp_path, f"tests/fixtures/{mkdocs_file}")
+    file = testproject_path / "site/index.html"
+    contents = file.read_text(encoding="utf8")
+    validate_static(contents)
+    validate_script(contents)
+    assert re.search(
+        r"document\$\.subscribe\(\(\) => { lightbox.reload\(\) }\);",
+        contents,
+    )
+    assert re.search(
+        r'<a class="glightbox".*?href="img\.png".*?>\s*<img.*?src="img\.png".*?\/><\/a>',
+        contents,
+    )
+
+
 def test_use_directory_urls(tmp_path):
     """
     Compatible with use_directory_urls is false or with --use-directory-urls and --use-directory-urls as args
@@ -691,3 +711,25 @@ def test_manual(tmp_path):
         r'<a class="glightbox".*?href="..\/img\.png".*?>\s*<img.*?src="..\/img\.png".*?\/><\/a>',
         contents,
     )
+
+    file = testproject_path / "site/manual_enable_by_page/index.html"
+    contents = file.read_text(encoding="utf8")
+    validate_static(contents, path="../")
+    validate_script(contents)
+    assert re.search(
+        r'<a class="glightbox".*?href="..\/img\.png".*?>\s*<img.*?alt="image-a" src="..\/img\.png".*?\/><\/a>',
+        contents,
+    )
+
+    assert (
+        re.search(
+            r'<a class="glightbox".*?href="..\/img\.png".*?>\s*<img.*?alt="image-b" src="..\/img\.png".*?\/><\/a>',
+            contents,
+        )
+        is None
+    )
+
+    assert re.search(
+        r'<a class="glightbox".*?href="..\/img\.png".*?>\s*<img.*?alt="image-c" src="..\/img\.png".*?\/><\/a>',
+        contents,
+    )
