feat: add support for page attribute

Signed-off-by: Jan Larwig <jan@larwig.com>

Author: yves-chevallier

README.md

@@ -1,11 +1,13 @@
 # MkDocs Plugin for embedding Drawio files
+
 [![Publish Badge](https://github.com/tuunit/mkdocs-drawio/workflows/Publish/badge.svg)](https://github.com/tuunit/mkdocs-drawio/actions)
 [![PyPI](https://img.shields.io/pypi/v/mkdocs-drawio)](https://pypi.org/project/mkdocs-drawio/)
 
 Sergey ([onixpro](https://github.com/onixpro)) is the original creator of this plugin but since his repository isn't maintained anymore we forked it on the 19th December of 2023 and have been keeping it up-to-date and expanding on the features since then. 
 [Buy Sergey a ☕](https://www.buymeacoffee.com/SergeyLukin) 
 
 ## Features
+
 This plugin enables you to embed interactive drawio diagrams in your documentation. Simply add your diagrams like you would any other image:
 
 ```markdown
@@ -25,18 +27,23 @@ Or you can use external urls:
 ![](https://example.com/diagram.drawio)
 ```
 
-Additionally this plugin supports multi page diagrams by using the `alt` text to select the pages by name:
+Additionally this plugin supports multi page diagrams by using either the `page` or `alt` property. To use the `page` property, you need to use the markdown extension `attr_list`.
 
 ```markdown
+Either use the alt text:
 ![Page-2](my-diagram.drawio)
 ![my-custom-page-name](my-diagram.drawio)
+
+Or use the page attribute:
+![Foo Diagram](my-diagram.drawio){ page="Page-2" }
+![Bar Diagram](my-diagram.drawio){ page="my-custom-page-name" }
 ```
 
 ## Setup
 
 Install plugin using pip:
 
-```
+```bash
 pip install mkdocs-drawio
 ```
 
@@ -67,7 +74,7 @@ plugins:
       toolbar: true  # control if hovering on a diagram shows a toolbar for zooming or not (default: true)
       tooltips: true # control if tooltips will be shown (default: true)
       edit: true     # control if edit button will be shown in the lightbox view (default: true)
-      border: 10     # increase or decrease the border / margin around your diagrams (default: 5) 
+      border: 10     # increase or decrease the border / margin around your diagrams (default: 5)
 ```
 
 ## Material Integration
@@ -106,7 +113,6 @@ document$.subscribe(({ body }) => {
 4. Searches through the generated html for all `img` tags that have a source of type `.drawio`
 5. Replaces the found `img` tags with `mxgraph` html blocks (actual drawio diagram content). For more details, please have a look at the [official drawio.com documentation](https://www.drawio.com/doc/faq/embed-html).
 
-
 ## Contribution guide
 
 1. Setup a virtual environment: `python3 -m venv venv && source venv/bin/activate`

examples/docs/tests/pagging/index.md

@@ -1,26 +1,61 @@
 # Pagging
 
-## Examples
-
-Below you should see diagram Page-1:
-![Page-1](test.drawio)
-
-Below you should see diagram Page-2:
-![Page-2](test.drawio)
-
-Below you should see Page-1 (default) because the specified Page-3 has not been found:
-![Page-3](test.drawio)
+You can either use the `alt` text of the image for pagging or use an attribute
+page for pagging if you have the `attr_list` markdown extension installed in 
+your `mkdocs.yaml`.
 
-Furthoremore, you should see a warning in your mkdocs server similar to:
-
-```bash
-WARNING -  Warning: Found 0 results for page name 'Page-3' for diagram 'test.drawio' on path '/tmp/mkdocs_ce1qjhyn/test2'
+```yaml
+markdown_extensions:
+  - attr_list
 ```
 
-## Markdown
+## Examples
 
-```markdown
-![Page-1](test.drawio)
-![Page-2](test.drawio)
-![Page-3](test.drawio)
-```
+=== "Diagram"
+    Below you should see diagram Page-1:
+    ![Page-1](test.drawio)
+
+=== "Markdown"
+    ```markdown
+    ![Page-1](test.drawio)
+    ```
+
+---
+
+=== "Diagram"
+    Below you should see diagram Page-2:
+    ![Page-2](test.drawio)
+
+=== "Markdown"
+    ```markdown
+    ![Page-2](test.drawio)
+    ```
+
+---
+
+=== "Diagram"
+    Below you should see diagram Page-2 using the attribute page:
+    ![Some alt text](test.drawio){ page="Page-2" }
+
+=== "Markdown"
+    ```markdown
+    ![Some alt text](test.drawio){ page="Page-2" }
+    ```
+
+---
+
+=== "Diagram"
+    Below you should see Page-1 (default) because the specified Page-3 has not been found:
+    ![Page-3](test.drawio)
+    
+    Furthoremore, you should see a warning in your mkdocs server similar to:
+    
+    ```bash
+    WARNING -  Warning: Found 0 results for page name 'Page-3' for diagram 'test.drawio' on path '/tmp/mkdocs_ce1qjhyn/test2'
+    ```
+
+=== "Markdown"
+    ```markdown
+    If page doesn't exist it will fallback to the first page.
+    ![Page-3](test.drawio)
+    ```

mkdocs_drawio/plugin.py

@@ -1,6 +1,5 @@
 import re
 import json
-import mkdocs
 import string
 import logging
 from lxml import etree
@@ -9,55 +8,47 @@
 from pathlib import Path
 from bs4 import BeautifulSoup
 from mkdocs.plugins import BasePlugin
+from mkdocs.config import base, config_options as c
 
-# ------------------------
-# Constants and utilities
-# ------------------------
 SUB_TEMPLATE = string.Template(
     '<div class="mxgraph" style="max-width:100%;border:1px solid transparent;" data-mxgraph="$config"></div>'
 )
 
 LOGGER = logging.getLogger("mkdocs.plugins.diagrams")
 
 
-# ------------------------
-# Plugin
-# ------------------------
-class DrawioPlugin(BasePlugin):
+class DrawioConfig(base.Config):
+    """Configuration options for the Drawio Plugin"""
+
+    viewer_js = c.Type(
+        str, default="https://viewer.diagrams.net/js/viewer-static.min.js"
+    )
+    toolbar = c.Type(bool, default=True)
+    tooltips = c.Type(bool, default=True)
+    border = c.Type(int, default=0)
+    edit = c.Type(bool, default=True)
+
+
+class DrawioPlugin(BasePlugin[DrawioConfig]):
     """
     Plugin for embedding Drawio Diagrams into your MkDocs
     """
 
-    config_scheme = (
-        (
-            "viewer_js",
-            mkdocs.config.config_options.Type(
-                str, default="https://viewer.diagrams.net/js/viewer-static.min.js"
-            ),
-        ),
-        ("toolbar", mkdocs.config.config_options.Type(bool, default=True)),
-        ("tooltips", mkdocs.config.config_options.Type(bool, default=True)),
-        ("border", mkdocs.config.config_options.Type(int, default=0)),
-        ("edit", mkdocs.config.config_options.Type(bool, default=True)),
-    )
-
     def on_post_page(self, output_content, config, page, **kwargs):
         return self.render_drawio_diagrams(output_content, page)
 
     def render_drawio_diagrams(self, output_content, page):
         if ".drawio" not in output_content.lower():
             return output_content
 
-        plugin_config = self.config.copy()
-
         soup = BeautifulSoup(output_content, "html.parser")
 
         diagram_config = {
-            "toolbar": "zoom" if plugin_config["toolbar"] else None,
-            "tooltips": "1" if plugin_config["tooltips"] else "0",
-            "border": plugin_config["border"] + 5,
+            "toolbar": "zoom" if self.config.toolbar else None,
+            "tooltips": "1" if self.config.tooltips else "0",
+            "border": self.config.border + 5,
             "resize": "1",
-            "edit": "_blank" if plugin_config["edit"] else None,
+            "edit": "_blank" if self.config.edit else None,
         }
 
         # search for images using drawio extension
@@ -66,7 +57,7 @@ def render_drawio_diagrams(self, output_content, page):
             return output_content
 
         # add drawio library to body
-        lib = soup.new_tag("script", src=plugin_config["viewer_js"])
+        lib = soup.new_tag("script", src=self.config.viewer_js)
         soup.body.append(lib)
 
         # substitute images with embedded drawio diagram
@@ -79,9 +70,13 @@ def render_drawio_diagrams(self, output_content, page):
                     "html.parser",
                 )
             else:
+                diagram_page = diagram["alt"]
+                # Use page attribute instead of alt if it is set
+                if "page" in diagram:
+                    diagram_page = diagram["page"]
                 mxgraph = BeautifulSoup(
                     DrawioPlugin.substitute_with_file(
-                        diagram_config, path, diagram["src"], diagram["alt"]
+                        diagram_config, path, diagram["src"], diagram_page
                     ),
                     "html.parser",
                 )

pyproject.toml

@@ -1,10 +1,10 @@
 [tool.poetry]
 name = "mkdocs-drawio"
-version = "1.8.2"
+version = "1.9.0"
 description = "MkDocs plugin for embedding Drawio files"
 authors = [
     "Jan Larwig <jan@larwig.com>",
-    "Sergey Lukin <onixpro@gmail.com>"
+    "Sergey Lukin <onixpro@gmail.com>",
 ]
 license = "MIT"
 readme = "README.md"
@@ -19,9 +19,11 @@ packages = [
 
 [tool.poetry.dependencies]
 python = ">=3.8.0,<4.0"
+requests = ">=2.0"
+Jinja2 = ">=3.0"
 beautifulsoup4 = ">=4.0"
 lxml = ">=4.0"
-mkdocs = ">=1.3"
+mkdocs = ">=1.4"
 
 [tool.poetry.group.dev.dependencies]
 python = ">=3.8.0,<4.0"