From 7e4fac876ad2a08e6b1c42c1d2da8ed8bb9bc702 Mon Sep 17 00:00:00 2001 From: Yves Chevallier Date: Wed, 22 Jan 2025 13:58:24 +0100 Subject: [PATCH] feat: add support for page attribute Signed-off-by: Jan Larwig --- README.md | 14 ++++-- examples/docs/configuration.md | 8 +-- examples/docs/tests/pagging/index.md | 75 ++++++++++++++++++++-------- mkdocs_drawio/plugin.py | 53 +++++++++----------- pyproject.toml | 6 ++- 5 files changed, 97 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 19b0d32..7546f6a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # 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/) @@ -6,6 +7,7 @@ Sergey ([onixpro](https://github.com/onixpro)) is the original creator of this p [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: 0) ``` ## 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` diff --git a/examples/docs/configuration.md b/examples/docs/configuration.md index a5abd71..6900e31 100644 --- a/examples/docs/configuration.md +++ b/examples/docs/configuration.md @@ -21,13 +21,13 @@ plugins: # 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 + + # Control if edit button will be shown in the lightbox view + # (data-edit) + edit: true ``` ## 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: diff --git a/examples/docs/tests/pagging/index.md b/examples/docs/tests/pagging/index.md index 59ef829..e81d85d 100644 --- a/examples/docs/tests/pagging/index.md +++ b/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) + ``` diff --git a/mkdocs_drawio/plugin.py b/mkdocs_drawio/plugin.py index 21b0758..b7602a3 100644 --- a/mkdocs_drawio/plugin.py +++ b/mkdocs_drawio/plugin.py @@ -1,6 +1,5 @@ import re import json -import mkdocs import string import logging from lxml import etree @@ -9,10 +8,8 @@ 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( '
' ) @@ -20,27 +17,23 @@ 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) @@ -48,16 +41,14 @@ 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", ) diff --git a/pyproject.toml b/pyproject.toml index d20b2b1..1b24cc0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "mkdocs-drawio" -version = "1.8.2" +version = "1.9.0" description = "MkDocs plugin for embedding Drawio files" authors = [ "Jan Larwig ", @@ -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"