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
+
[](https://github.com/tuunit/mkdocs-drawio/actions)
[](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:
```
-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:
+
+Or use the page attribute:
+{ page="Page-2" }
+{ 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:
-
-
-Below you should see diagram Page-2:
-
-
-Below you should see Page-1 (default) because the specified Page-3 has not been found:
-
+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
-
-
-
-```
+=== "Diagram"
+ Below you should see diagram Page-1:
+ 
+
+=== "Markdown"
+ ```markdown
+ 
+ ```
+
+---
+
+=== "Diagram"
+ Below you should see diagram Page-2:
+ 
+
+=== "Markdown"
+ ```markdown
+ 
+ ```
+
+---
+
+=== "Diagram"
+ Below you should see diagram Page-2 using the attribute page:
+ { page="Page-2" }
+
+=== "Markdown"
+ ```markdown
+ { page="Page-2" }
+ ```
+
+---
+
+=== "Diagram"
+ Below you should see Page-1 (default) because the specified Page-3 has not been found:
+ 
+
+ 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.
+ 
+ ```
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"