feat: configurable toolbar (#36)

* feat: configurable toolbar

Co-authored-by: Yves Chevallier <yves.chevallier@heig-vd.ch>
Signed-off-by: Jan Larwig <jan@larwig.com>

* bump to v1.13.0 and attribution for another author

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

---------

Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Yves Chevallier <yves.chevallier@heig-vd.ch>

Author: tuunit

README.md

@@ -71,12 +71,20 @@ Further options are:
 ```yaml
 plugins:
   - drawio:
-      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: 0)
-      darkmode: true       # support darkmode. allows for automatic switching between dark and lightmode based on the theme toggle. (default: false)
-      highlight: "#0000FF" # color hyperlinks on mouse hover over (default: no color)
+      tooltips: true       # Enable tooltips on diagram elements
+      border: 5            # Border size / padding around diagrams
+      edit: true           # Enable opening the editor for diagrams
+      darkmode: true       # Enable dark mode support (classic MkDocs and Material)
+      highlight: "#0000FF" # Highlight color for hyperlinks
+      lightbox: true       # Enable opening the lightbox on click
+      toolbar:             # Control the looks and behaviour of the toolbar
+        pages: true        # Display the page selector
+        tags: true         # Display the tags selector
+        zoom: true         # Display the zoom controls
+        layers: true       # Display the layer controls
+        lightbox: true     # Display the lightbox / fullscreen button
+        position: "top"    # Control the position of the toolbar (top or bottom)
+        no_hide: false     # Do not hide the toolbar when not hovering over diagrams
 ```
 
 ## Material Integration

examples/docs/configuration.md

@@ -15,44 +15,56 @@ 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: true
 
-      # Control if tooltips will be shown (data-tooltips)
+      # URL to the Drawio viewer JavaScript file
+      viewer_js: "https://viewer.diagrams.net/js/viewer-static.min.js"
+
+      # Enable tooltips on diagram elements
       tooltips: true
 
-      # Increase or decrease the padding around your diagrams
-      # (data-border)
+      # Border size / padding around diagrams
       border: 5
 
-      # Control if edit button will be shown in the lightbox view
-      # (data-edit)
+      # Enable opening the editor for diagrams
       edit: true
 
-      # Control if darkmode is supported
+      # Enable dark mode support
       # When activated the color scheme for your diagrams is automatically toggled
       # based on the selected theme. Supports classic mkdocs and mkdocs-material.
       darkmode: true 
 
-      # Set the color of hyperlink highlighting
+      # Highlight color for hyperlinks
       # When a diagram element has a hyperlink on it, the element is highlighted
-      # on mouse hover over to better indicate a hylerlink is present. This
-      # parameter controls the color of the highlight boarder. If omitted, no
-      # highlighting happens.
+      # on mouse hover over to better indicate a hyperlink is present.
       highlight: "#0000FF"
-```
-## 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`:
+      # Enable to open the lightbox on click
+      lightbox: true
 
-```yaml
-markdown_extensions:
-  - attr_list
+      # Toolbar specific options
+      toolbar:
+        # Display the page selector
+        pages: true
+
+        # Display the tags selector
+        tags: true
+
+        # Display the zoom controls
+        zoom: true
+
+        # Display the layer controls
+        layers: true
+
+        # Display the lightbox / fullscreen button
+        lightbox: true
+
+        # Position of the toolbar (top/bottom)
+        position: "top"
+
+        # Do not hide the toolbar when not hovering over diagrams
+        no_hide: false
 ```
+
 ## Material Integration
 
 If you are using the Material Theme and want to use the [instant-loading](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=instant#instant-loading) feature. You will have to configure the following:

examples/mkdocs-classic.yml

@@ -1,35 +1,41 @@
-site_name: test_mkdocs_drawio
+site_name: MkDocs Drawio Plugin
 docs_dir: docs
+
 nav:
   - Documentation:
       - Getting Started: index.md
       - Configuration: configuration.md
       - Plumbing: plumbing.md
-  - Tests:
-    - Simple Diagram: 'tests/simple-diagram/index.md'
-    - Error Handling: 'tests/error-handling/index.md'
-    - Configuration: 'tests/configuration/index.md'
-    - Code Blocks: 'tests/code-blocks/index.md'
-    - Relative Paths (a): 'tests/relative-paths/index.md'
-    - Relative Paths (b): 'tests/relative-paths/example.md'
-    - Pagging: 'tests/pagging/index.md'
-    - External URL: 'tests/external-url/index.md'
-    - SVG Diagram: 'tests/svg/index.md'
+  - Examples:
+      - Simple Diagram: "tests/simple-diagram/index.md"
+      - Error Handling: "tests/error-handling/index.md"
+      - Configuration: "tests/configuration/index.md"
+      - Code Blocks: "tests/code-blocks/index.md"
+      - Relative Paths (Index): "tests/relative-paths/index.md"
+      - Relative Paths (Subpage): "tests/relative-paths/example.md"
+      - Pagging: "tests/pagging/index.md"
+      - External URL: "tests/external-url/index.md"
+      - SVG Diagram: "tests/svg/index.md"
+      - Hyperlinks: "tests/hyperlinks/index.md"
 
 theme:
-    name: mkdocs
-    user_color_mode_toggle: true
+  name: mkdocs
+  user_color_mode_toggle: true
 
 plugins:
-    - search
-    - drawio:
-        toolbar: true
-        tooltips: true
-        edit: true
-        border: 20
-        darkmode: true
-    - print-site
-
+  - search
+  - drawio:
+      toolbar:
+        position: "bottom"
+        zoom: true
+        lightbox: false # Hide the lightbox button from the toolbar
+      lightbox: true # Still allow clicking on the diagram to open the lightbox
+      tooltips: true
+      edit: true
+      border: 20
+      darkmode: true
+      highlight: "#0000FF"
+  - print-site
 
 markdown_extensions:
   - attr_list

examples/mkdocs.yml

@@ -45,7 +45,11 @@ markdown_extensions:
 plugins:
   - search
   - drawio:
-      toolbar: true
+      toolbar:
+        position: "bottom"
+        zoom: true
+        lightbox: false # Hide the lightbox button from the toolbar
+      lightbox: true # Still allow clicking on the diagram to open the lightbox
       tooltips: true
       edit: true
       border: 20

mkdocs_drawio/plugin.py

@@ -3,9 +3,9 @@
 import string
 import logging
 from lxml import etree
-from typing import Dict
 from html import escape
 from pathlib import Path
+from typing import Dict
 from bs4 import BeautifulSoup
 from mkdocs.utils import copy_file
 from mkdocs.plugins import BasePlugin
@@ -18,43 +18,132 @@
 LOGGER = logging.getLogger("mkdocs.plugins.diagrams")
 
 
+class Toolbar(base.Config):
+    """Configuration options for the toolbar, mostly taken from
+    https://www.drawio.com/doc/faq/embed-html-options
+    """
+
+    pages = c.Type(bool, default=True)
+    """ Display the page selector """
+
+    tags = c.Type(bool, default=True)
+    """ Display the tags selector """
+
+    zoom = c.Type(bool, default=True)
+    """ Display the zoom controls """
+
+    layers = c.Type(bool, default=True)
+    """ Display the layer controls """
+
+    lightbox = c.Type(bool, default=True)
+    """ Display the lightbox / fullscreen button """
+
+    position = c.Choice(["top", "bottom"], default="bottom")
+    """ Position of the toolbar """
+
+    no_hide = c.Type(bool, default=False)
+    """ Do not hide the toolbar when not hovering over diagrams """
+
+
 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)
+    """ URL to the Drawio viewer JavaScript file """
+
+    toolbar = c.Type((bool, dict), default=True)
+    """ Configuration for the toolbar.
+
+    Can be a bool or a dict. If bool, enables or disables the toolbar
+    completely. If dict, allows to configure individual toolbar items.
+    """
+
     tooltips = c.Type(bool, default=True)
+    """ Enable tooltips on diagram elements """
+
     border = c.Type(int, default=0)
+    """ Border size / padding around diagrams """
+
     edit = c.Type(bool, default=True)
+    """ Enable opening the editor for diagrams """
+
     darkmode = c.Type(bool, default=False)
+    """ Enable dark mode support """
+
     highlight = c.Type(str, default="")
+    """ Highlight color for hyperlinks """
+
+    lightbox = c.Type(bool, default=True)
+    """ Enable to open the lightbox on click """
 
 
 class DrawioPlugin(BasePlugin[DrawioConfig]):
     """
     Plugin for embedding Drawio Diagrams into your MkDocs
     """
 
-    def on_post_page(self, output_content, config, page, **kwargs):
-        return self.render_drawio_diagrams(output_content, page)
+    def get_diagram_config(self) -> Dict:
+        """Build diagram config using only global plugin settings."""
 
-    def render_drawio_diagrams(self, output_content, page):
-        if ".drawio" not in output_content.lower():
-            return output_content
+        toolbar_items = []
 
-        soup = BeautifulSoup(output_content, "html.parser")
+        if self.toolbar_config.pages:
+            toolbar_items.append("pages")
+        if self.toolbar_config.tags:
+            toolbar_items.append("tags")
+        if self.toolbar_config.zoom:
+            toolbar_items.append("zoom")
+        if self.toolbar_config.layers:
+            toolbar_items.append("layers")
+        if self.toolbar_config.lightbox:
+            toolbar_items.append("lightbox")
+
+        toolbar_value = " ".join(toolbar_items) if toolbar_items else None
 
-        diagram_config = {
-            "toolbar": "zoom" if self.config.toolbar else None,
+        config = {
+            "toolbar-position": self.toolbar_config.position,
+            "toolbar-nohide": "1" if self.toolbar_config.no_hide else "0",
             "tooltips": "1" if self.config.tooltips else "0",
             "border": self.config.border + 5,
             "resize": "1",
             "edit": "_blank" if self.config.edit else None,
-            "highlight": self.config.highlight if self.config.highlight else None,
+            "highlight": self.config.highlight or None,
+            "lightbox": "1" if self.config.lightbox else "0",
         }
 
+        if toolbar_value is not None:
+            config["toolbar"] = toolbar_value
+
+        return {key: value for key, value in config.items() if value is not None}
+
+    def get_toolbar_config(self, toolbar_config) -> Toolbar:
+        config = Toolbar()
+
+        # Bool means enable defaults or disable completely.
+        if isinstance(toolbar_config, bool):
+            if toolbar_config is False:
+                # Flip all toolbar items off but keep other defaults intact.
+                for key in ("pages", "tags", "zoom", "layers", "lightbox"):
+                    setattr(config, key, False)
+
+        if isinstance(toolbar_config, dict):
+            # Load values through mkdocs config validation to respect defaults.
+            config.load_dict(toolbar_config)
+
+        config.validate()
+        return config
+
+    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
+
+        soup = BeautifulSoup(output_content, "html.parser")
+
         # search for images using drawio extension
         diagrams = soup.find_all(
             "img", src=re.compile(r".*\.drawio(.svg)?$", re.IGNORECASE)
@@ -69,6 +158,8 @@ def render_drawio_diagrams(self, output_content, page):
         # substitute images with embedded drawio diagram
         path = Path(page.file.abs_dest_path).parent
 
+        diagram_config = self.get_diagram_config()
+
         for diagram in diagrams:
             if re.search("^https?://", diagram["src"]):
                 mxgraph = BeautifulSoup(
@@ -144,7 +235,10 @@ def parse_diagram(data, page_name, src="", path=None) -> str:
         return etree.tostring(mxfile, encoding=str)
 
     def on_config(self, config: base.Config):
-        """Load embedded files"""
+        # Prepare toolbar configuration
+        self.toolbar_config = self.get_toolbar_config(self.config.toolbar)
+
+        # Prepare list of embedded files
         self.base = Path(__file__).parent
         self.css = []
         self.js = []

pyproject.toml

@@ -1,9 +1,10 @@
 [tool.poetry]
 name = "mkdocs-drawio"
-version = "1.12.2"
+version = "1.13.0"
 description = "MkDocs plugin for embedding Drawio files"
 authors = [
     "Jan Larwig <jan@larwig.com>",
+    "Yves Chevallier <yves.chevallier@heig-vd.ch>",
     "Sergey Lukin <onixpro@gmail.com>"
 ]
 license = "MIT"