feat: add dynamic theme colors and attr_list support for paging

.github/workflows/ci.yml

@@ -10,14 +10,38 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-    
-      - name: Set up Python 
+
+      - name: Set up Python
         uses: actions/setup-python@v4
         with:
           python-version: "3.x"
-
-      - name: Install pypa/build
-        run: python3 -m pip install build poetry --user
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+      - name: Check
+        run: |
+            poetry run ruff check .
+            poetry run black --check .
+
+      - name: Install
+        run: poetry install
 
-      - name: Test the build 
-        run: python3 -m build
+      - name: Build
+        run: poetry build
+  documentation:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags')
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+      - name: Build site
+        run: |
+          poetry install
+          poetry run mkdocs build -f documentation/mkdocs-material.yml
+      - name: Build and Deploy
+        uses: JamesIves/[email protected]
+        with:
+          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: documentation/site

.gitignore

@@ -158,3 +158,9 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
+
+# Backups generated from the Desktop application
+*.drawio.bkp
+
+# Temporary files generated by Windows on WSL
+*:Zone.Identifier

README.md

@@ -1,12 +1,14 @@
 # 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/)
 
-[Buy Sergey a ☕](https://www.buymeacoffee.com/SergeyLukin) 
+[Buy Sergey a ☕](https://www.buymeacoffee.com/SergeyLukin)
 
 Sergey ([onixpro](https://github.com/onixpro)) is the original creator of this plugin. Repo can be found [here.](https://github.com/onixpro/mkdocs-drawio-file)
 
 ## Features
+
 This plugin enables you to embed interactive drawio diagrams in your documentation. Simply add your diagrams like you would any other image:
 
 ```markdown
@@ -26,18 +28,27 @@ 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`.
+
+With `alt_as_page: True` which is the default:
 
 ```markdown
 ![Page-2](my-diagram.drawio)
 ![my-custom-page-name](my-diagram.drawio)
 ```
 
+With `alt_as_page: False`:
+
+```markdown
+![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
 ```
 
@@ -68,7 +79,8 @@ 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)
+      alt_as_page: true # use the alt text as page name (default: false)
 ```
 
 ## Material Integration
@@ -107,7 +119,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. Either use the devcontainer or setup a venv with mkdocs installed

documentation/docs/circle-square.drawio

@@ -0,0 +1,17 @@
+<?xml version='1.0' encoding='utf-8'?>
+<mxfile version="26.0.7">
+  <diagram name="Page-1" id="mV4jbraemd7C51ydpzk2">
+    <mxGraphModel dx="565" dy="355" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="394" pageHeight="394" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="7JHgTfKEjFP575Ptm9la-1" value="" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;" vertex="1" parent="1">
+          <mxGeometry x="80" y="40" width="80" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="7JHgTfKEjFP575Ptm9la-2" value="" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">
+          <mxGeometry x="180" y="40" width="80" height="80" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

documentation/docs/configuration.md

@@ -0,0 +1,98 @@
+# Configuration
+
+## Diagram options
+
+By default the plugin uses the official url for the minified drawio javascript library. To use a custom source for the drawio viewer you can overwritte the url. This might be useful in airlocked environments.
+
+```yaml
+plugins:
+  - drawio:
+      viewer_js: "https://viewer.diagrams.net/js/viewer-static.min.js"
+```
+
+Further options are the following with their default value
+
+```yaml
+plugins:
+  - drawio:
+      # Control if hovering on a diagram shows a toolbar for zooming or not
+      toolbar:
+        # Display the zoom control (data-toolbar-zoom)
+        zoom: true
+
+        # Display the page selector (data-toolbar-pages)
+        pages: true
+
+        # Display the layers control (data-toolbar-layers)
+        layers: true
+
+        # Display the lightbox button (data-toolbar-lightbox)
+        lightbox: true
+
+        # Do not hide the toolbar when hovering over the diagram
+        # (data-toolbar-nohide)
+        nohide: false
+
+        # Control the position of the toolbar (top or bottom)
+        # (data-toolbar-position)
+        position: "top"
+
+      # Control if tooltips will be shown (data-tooltips)
+      tooltips: true
+
+      # Control if edit button will be shown in the lightbox view
+      # (data-edit)
+      edit: true
+
+      # Increase or decrease the padding around your diagrams
+      # (data-border)
+      border: 5
+
+      # Use the alt text as page name
+      alt_as_page: false
+```
+
+## HTML Attributes
+
+For each global configuration option you can also use the attribute in the diagram itself. This will override the global configuration. Here is an example:
+
+```markdown
+![](my-diagram.drawio){ data-toolbar-zoom="false" }
+```
+
+To use these attributes you need to enable the markdown extension `attr_list` in your `mkdocs.yml`:
+
+```yaml
+markdown_extensions:
+  - attr_list
+```
+
+## Page selection
+
+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`.
+
+By default this attribute is `True`. If you use other plugins such as `mkdocs-caption` you might want to keep `alt` for the caption.
+
+=== "`alt_as_page: True`"
+
+    ```markdown
+    ![Page-2](my-diagram.drawio)
+    ![my-custom-page-name](my-diagram.drawio)
+    ```
+
+=== "`alt_as_page: False`"
+
+    ```markdown
+    ![Foo Diagram](my-diagram.drawio){ page="Page-2" }
+    ![Bar Diagram](my-diagram.drawio){ page="my-custom-page-name" }
+    ```
+
+In your `mkdocs.yml` you can configure the plugin to use the `alt` property instead of the `page` property:
+
+```yaml
+markdown_extensions:
+  - attr_list
+plugins:
+  - drawio:
+      alt_as_page: False
+```

documentation/docs/index.md

@@ -0,0 +1,57 @@
+# MkDocs Drawio Plugin
+
+This plugin allows you to embed draw.io diagrams in your MkDocs documentation. It is compatible with most MkDocs themes, but specifically tested with the Material theme and the MkDocs default theme.
+
+Sergey ([onixpro](https://github.com/onixpro)) is the original creator of this plugin. Repo can be found [here.](https://github.com/onixpro/mkdocs-drawio-file)
+
+## Installation
+
+Install the plugin using pip or poetry:
+
+```bash
+pip install mkdocs-drawio
+```
+
+or
+
+```bash
+poetry add mkdocs-drawio
+```
+
+Then add the plugin to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - drawio
+```
+
+## Features
+
+The currently supported features are:
+
+- Embed draw.io diagrams in your documentation to keep a single source of truth.
+- Use diagrams hosted within your own docs or external urls.
+- Support for multi page diagrams by selecting which page to display.
+- Compatible with `mkdocs-caption` and `mkdocs-glightbox`.
+- Match the diagram theme with your MkDocs theme (light, dark/slate).
+- Zoom in/out.
+- Full screen preview.
+- Print or edit button.
+
+## Usage
+
+Simply add an image as you would normally do in markdown:
+
+```markdown
+Absolute path:
+![](/assets/my-diagram.drawio)
+
+Same directory as the markdown file:
+![](my-diagram.drawio)
+
+Relative directory to the markdown file:
+![](../my-diagram.drawio)
+
+Or you can use external urls:
+![](https://example.com/diagram.drawio)
+```

documentation/docs/plumbing.md

@@ -0,0 +1,51 @@
+# Plumbing and internals
+
+For those who want to understand how the plugin works, here is a brief overview.
+
+## Diagrams.net
+
+**Diagrams.net** previoully known as **Draw.io** is a free online diagram software. It is perfect for creating diagrams, flowcharts, process diagrams, and more. It is a powerful tool that can be used for creating diagrams for any purpose.
+
+It relies on JTGraph's [mxGraph](https://jgraph.github.io/mxgraph/) library to render the diagrams. A mxGraph is a XML-based language that defines the structure of the diagram. Here an example
+
+![](circle-square.drawio)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="app.diagrams.net" version="26.0.7">
+  <diagram name="Page-1" id="mV4jbraemd7C51ydpzk2">
+    <mxGraphModel dx="565" dy="355" grid="1" gridSize="10"
+        guides="1" tooltips="1" connect="1" arrows="1" fold="1"
+        page="1" pageScale="1" pageWidth="394" pageHeight="394"
+        math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="7JHgTfKEjFP575Ptm9la-1" value=""
+            style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;"
+            vertex="1" parent="1">
+          <mxGeometry x="80" y="40" width="80" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="7JHgTfKEjFP575Ptm9la-2" value=""
+            style="whiteSpace=wrap;html=1;aspect=fixed;
+                   fillColor=#f8cecc;strokeColor=#b85450;"
+            vertex="1" parent="1">
+          <mxGeometry x="180" y="40" width="80" height="80" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
+```
+
+## GraphViewer
+
+The plugin uses the [GraphViewer](https://github.com/jgraph/drawio/blob/dev/src/main/webapp/js/viewer-static.min.js) minified version of the drawio viewer.
+
+This is a standalone viewer for drawio diagrams that can be embedded in any web page to convert mxGraph XML to SVG. It features a lightbox mode and a toolbar with buttons to zoom, edit, and navigate the diagram.
+
+## The Plugin
+
+This plugin heavily relies on the GraphViewer to render the diagrams. The MkDocs plugin is responsible for passing configuration options to the viewer and ensure compatibility across MkDocs themes.
+
+Furthermore, it provides a way to extract pages from diagrams to only serve the necessary content to the user. This is useful when you have a large diagram and only want to show a specific part of it.

example/docs/tests/configuration/tooltips.drawio → documentation/docs/tests/assets/test.drawio

@@ -1,32 +1,30 @@
-<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36" version="24.7.7">
+<mxfile version="24.7.8">
   <diagram id="sWgCjdYztQFh1ezxrF-R" name="Page-1">
-    <mxGraphModel dx="963" dy="1401" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+    <mxGraphModel dx="1420" dy="942" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
       <root>
         <mxCell id="0" />
         <mxCell id="1" parent="0" />
-        <mxCell id="2" value="a" style="whiteSpace=wrap;html=1;aspect=fixed;" parent="1" vertex="1">
+        <mxCell id="2" value="a" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=none;" parent="1" vertex="1">
           <mxGeometry x="80" y="60" width="80" height="80" as="geometry" />
         </mxCell>
-        <mxCell id="3" value="" style="endArrow=classic;startArrow=classic;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" parent="1" source="2" target="4" edge="1">
+        <mxCell id="3" value="" style="endArrow=classic;startArrow=classic;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;fillColor=#f8cecc;strokeColor=#b85450;" parent="1" source="2" target="4" edge="1">
           <mxGeometry width="50" height="50" relative="1" as="geometry">
             <mxPoint x="320" y="160" as="sourcePoint" />
             <mxPoint x="380" y="140" as="targetPoint" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="4" value="c" style="ellipse;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+        <mxCell id="4" value="c" style="ellipse;whiteSpace=wrap;html=1;fillColor=none;" parent="1" vertex="1">
           <mxGeometry x="310" y="60" width="120" height="80" as="geometry" />
         </mxCell>
-        <mxCell id="5" value="" style="whiteSpace=wrap;html=1;aspect=fixed;" parent="1" vertex="1">
-          <mxGeometry x="360" y="250" width="80" height="80" as="geometry" />
+        <mxCell id="5" value="" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1">
+          <mxGeometry x="390" y="260" width="80" height="80" as="geometry" />
         </mxCell>
-        <mxCell id="6" value="" style="triangle;whiteSpace=wrap;html=1;" parent="1" vertex="1">
-          <mxGeometry x="110" y="250" width="60" height="80" as="geometry" />
+        <mxCell id="6" value="" style="triangle;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;" parent="1" vertex="1">
+          <mxGeometry x="200" y="270" width="60" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="7" value="Diagram from assets directory" style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;" parent="1" vertex="1">
+          <mxGeometry x="180" y="195" width="180" height="30" as="geometry" />
         </mxCell>
-        <UserObject label="Hover over me." tooltip="Hello I&#39;m a tooltip." id="cVhbZjsc7NjAtHNjXZGz-8">
-          <mxCell style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;" vertex="1" parent="1">
-            <mxGeometry x="210" y="190" width="110" height="30" as="geometry" />
-          </mxCell>
-        </UserObject>
       </root>
     </mxGraphModel>
   </diagram>