diff --git a/README.md b/README.md index c5ddf78..9f6da47 100644 --- a/README.md +++ b/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 diff --git a/examples/docs/configuration.md b/examples/docs/configuration.md index d2b13d4..1b7cfc8 100644 --- a/examples/docs/configuration.md +++ b/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: diff --git a/examples/mkdocs-classic.yml b/examples/mkdocs-classic.yml index 1bcb3c1..57488ff 100644 --- a/examples/mkdocs-classic.yml +++ b/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 diff --git a/examples/mkdocs.yml b/examples/mkdocs.yml index 9d045a2..95673bd 100644 --- a/examples/mkdocs.yml +++ b/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 diff --git a/mkdocs_drawio/plugin.py b/mkdocs_drawio/plugin.py index 6e99685..cb3209c 100644 --- a/mkdocs_drawio/plugin.py +++ b/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,18 +18,65 @@ 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]): @@ -37,24 +84,66 @@ 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 = [] diff --git a/pyproject.toml b/pyproject.toml index e813544..0dbe793 100644 --- a/pyproject.toml +++ b/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 ", + "Yves Chevallier ", "Sergey Lukin " ] license = "MIT"