feat: add dynamic theme colors and attr_list support for paging #21

yves-chevallier · 2025-01-23T09:15:06Z

I was about to write another Draw.io plugin for MkDocs when I came across yours. It's simple and effective, but I found myself missing a few features:

Avoid using the alt text of the image for pages, as I'm using mkdocs-caption.
Adjust the drawing theme automatically based on the color scheme (light/dark).
Remove specifics tied to the theme in use (e.g., mkdocs/material).

To maintain backward compatibility, I've added an alt_as_page option, which defaults to true. When set to false, the page can instead be specified using an attribute (requires attr_list to be enabled):

![Image Caption](image.png){ page="pageName" }

I also took the opportunity to modernize the configuration by using the DrawioConfig(base.Config) class.

Lastly, your plugin currently works only with light themes. Fortunately, Draw.io recently added support for the color-scheme attribute in their viewer, allowing for theme adjustments. Since this requires a bit of JavaScript and CSS, the plugin now automatically copies the necessary files, so there’s no need to add any extra resources manually.

This is just a draft proposal for now—let me know your thoughts!

tuunit

Overall great addition to the project 👏🏼
Just some nit-picks and questions.

pyproject.toml

example/requirements.txt

example/docs/tests/assets/test.drawio

example/docs/tests/configuration/math.drawio

tuunit · 2025-01-23T10:16:53Z

example/docs/tests/configuration/tooltips.drawio

@@ -1,32 +1,41 @@
-<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 host="Electron" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.7.8 Chrome/128.0.6613.36 Electron/32.0.1 Safari/537.36" version="24.7.8">


Suggested change

<mxfile host="Electron" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.7.8 Chrome/128.0.6613.36 Electron/32.0.1 Safari/537.36" version="24.7.8">

<mxfile>

I understand from what it comes. I am using the standalone version Draw.io which is using Electron instead of the browser. Yes this should be removed, but the page and version attribute should remain in the tag <mxfile>. We can fix all drawings with a script:

import os import xml.etree.ElementTree as ET def clean_drawio_files(directory="."): """ Look for all .drawio files in the given directory and its subdirectories and remove the host and agent attributes from the mxfile element if they exist. """ for root, _, files in os.walk(directory): for file in files: if file.endswith(".drawio"): file_path = os.path.join(root, file) try: tree = ET.parse(file_path) root_element = tree.getroot() if root_element.tag == "mxfile": changed = False for attr in ["host", "agent"]: if attr in root_element.attrib: del root_element.attrib[attr] changed = True if changed: tree.write(file_path, encoding="utf-8", xml_declaration=True) print(f"Nettoyé : {file_path}") else: print(f"Aucun changement : {file_path}") except Exception as e: print(f"Erreur lors du traitement de {file_path} : {e}") if __name__ == "__main__": clean_drawio_files()

I have added that script it can be run with:

poetry run python scripts/clean_drawio_files.py

.gitignore

tuunit · 2025-01-23T10:21:08Z

README.md

@@ -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)


Small thing but can you indent all comments to the same level?

mkdocs_drawio/plugin.py

pyproject.toml

Co-authored-by: Jan Larwig <jan@larwig.com>

tuunit · 2025-01-23T16:24:36Z

mkdocs_drawio/js/drawio.js

+if (typeof document$ !== "undefined" && typeof document$.subscribe === "function") {
+    document$.subscribe(({ body }) => {
+        GraphViewer.processElements()
+        colorize();
+      });
+} else {


This will automatically back in support for the instant reload of material themes. Therefore the explanation for how to manually add it should be removed from the README.

Furthermore, I would like to have a comment explaining the necessity of this if-else block. Because a couple of weeks or months down the round no one will remember why this code exists.

mkdocs_drawio/plugin.py

yves-chevallier · 2025-01-24T15:58:00Z

I have made significant changes. Let me know what you think!

I added features that allow customizing the appearance of the drawing. The test site was renamed to “documentation.” In principle (though not tested yet), the documentation is automatically uploaded to GitHub Pages. Since it is now a complete plugin documentation, it can be made available to all users.

I’m going on vacation for three weeks, so let’s discuss everything when I get back. If you agree with these changes, you could bump the version to 2.0.0, given how extensive they are compared to the original plugin.

For your information, I am interested to this plugin for my online course (https://heig-tin-info.github.io/handbook/) which uses a lot of draw.io. I am currently using a home made hook and the idea is to rely on a standalone plugin for drawio.

tuunit · 2025-01-25T11:27:09Z

I have made significant changes. Let me know what you think!

I added features that allow customizing the appearance of the drawing. The test site was renamed to “documentation.” In principle (though not tested yet), the documentation is automatically uploaded to GitHub Pages. Since it is now a complete plugin documentation, it can be made available to all users.

I’m going on vacation for three weeks, so let’s discuss everything when I get back. If you agree with these changes, you could bump the version to 2.0.0, given how extensive they are compared to the original plugin.

For your information, I am interested to this plugin for my online course (https://heig-tin-info.github.io/handbook/) which uses a lot of draw.io. I am currently using a home made hook and the idea is to rely on a standalone plugin for drawio.

Hi @yves-chevallier,

thanks again for contributing and the changes you made are amazing ⭐ but we should have introduced the changes in multiple PRs. This way people could gradually adopt the changes and published versions. Furthermore from a review perspective this PR got out of hand.

Don't get me wrong. The work and cleanup you have done looks great and we will make it work.

yves-chevallier · 2025-01-25T11:33:34Z

Yes I agree, once I come back I close the PR and reopen some with gradual changes

tuunit

Haven't reviewed everything yet.

tuunit · 2025-01-25T11:29:03Z

.github/workflows/ci.yml

+      - name: Install Poetry
+        uses: snok/install-poetry@v1


Why unnecessary introduce another dependency to such a small project?
We can just do the install of poetry as before.

- name: Install pypa/build run: python3 -m pip install build poetry --user

tuunit · 2025-01-25T11:30:52Z

.github/workflows/ci.yml

+      - name: Build and Deploy
+        uses: JamesIves/github-pages-deploy-action@4.7.2
+        with:
+          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: documentation/site


Same goes for this one. Lets use the official GitHub Action for deploying pages:
https://github.com/actions/deploy-pages

tuunit · 2025-01-25T11:32:25Z

documentation/docs/index.md

+
+## Usage
+
+Simply add an image as you would normally do in markdown:


Suggested change

Simply add an image as you would normally do in markdown:

Simply add your drawio files like you would any other image in markdown:

tuunit · 2025-01-25T11:33:36Z

documentation/docs/plumbing.md

+## 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.


Never blindly trust LLMs ;)

Suggested change

## 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.

## Draw.io

**Draw.io** previoully known as **Diagrams.net** is a free online diagram software. It is perfect for creating diagrams, flowcharts, process diagrams, and more.

tuunit · 2025-01-25T11:37:19Z

documentation/docs/plumbing.md

+
+**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


Suggested change

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

It relies on JGraph's [mxGraph](https://jgraph.github.io/mxgraph/) library to render the diagrams. A mxGraph uses XML to define the structure of diagrams. Here an example

tuunit · 2025-01-25T11:38:31Z

documentation/docs/plumbing.md

+
+## 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.


Suggested change

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.

The plugin uses the minified version of the [drawio viewer](https://github.com/jgraph/drawio/blob/dev/src/main/webapp/js/viewer-static.min.js).

tuunit · 2025-01-25T11:40:14Z

documentation/docs/tests/code-blocks/index.md

@@ -0,0 +1,7 @@
+# Code Blocks
+
+Diagrams are not rendered in code blocks. So you don't have to worry about the diagram being rendered in the code block.


Suggested change

Diagrams are not rendered in code blocks. So you don't have to worry about the diagram being rendered in the code block.

Diagrams are not rendered in code blocks. So you don't have to worry if you want to explain how to embed drawio diagrams in your own docs.

tuunit · 2025-01-25T11:43:28Z

mkdocs_drawio/plugin.py

+    border = c.Optional(c.Type(int))
+    padding = c.Type(int, default=10)
+    """ Padding around the diagram, border will be deprecated
+    but kept for backwards compatibility """


Suggested change

border = c.Optional(c.Type(int))

padding = c.Type(int, default=10)

""" Padding around the diagram, border will be deprecated

but kept for backwards compatibility """

border = c.Optional(c.Type(int))

""" Deprecated: Use the padding option instead """

padding = c.Type(int, default=10)

""" Padding around the diagram """

tuunit · 2025-01-25T11:46:51Z

poetry.lock

Please remove the poetry.lock file and put it into the .gitignore

tuunit · 2025-01-25T11:47:42Z

pyproject.toml

+poetry = { version = "^2.0", python = ">=3.9" }  # Marqueur d'environnement
+black = { version = ">=24.0", python = ">=3.9" } # Pareil pour black


Suggested change

poetry = { version = "^2.0", python = ">=3.9" } # Marqueur d'environnement

black = { version = ">=24.0", python = ">=3.9" } # Pareil pour black

poetry = { version = "^2.0", python = ">=3.9" }

black = { version = ">=24.0", python = ">=3.9" }

yves-chevallier added 2 commits January 22, 2025 13:58

Add alt_as_page

5efade9

Adapt colorscheme and dynamic module versionning

a1ef253

tuunit requested changes Jan 23, 2025

View reviewed changes

tuunit changed the title ~~Add config option, light refactoring, dynamic theme colors.~~ feat: add dynamic theme colors and attr_list support for paging Jan 23, 2025

yves-chevallier and others added 3 commits January 23, 2025 12:13

Update example/docs/tests/assets/test.drawio

30db9a6

Co-authored-by: Jan Larwig <jan@larwig.com>

Fix co-author email

58aec35

Co-authored-by: Jan Larwig <jan@larwig.com>

Add clean script and fix drawio

83c082f

tuunit requested changes Jan 23, 2025

View reviewed changes

yves-chevallier added 3 commits January 24, 2025 01:08

Add config options, work on documentation

4381706

Clean drawio files

a92d841

Update ci.yml

e7d7ed2

tuunit requested changes Jan 25, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add dynamic theme colors and attr_list support for paging #21

feat: add dynamic theme colors and attr_list support for paging #21

yves-chevallier commented Jan 23, 2025

tuunit left a comment

tuunit Jan 23, 2025

yves-chevallier Jan 23, 2025

yves-chevallier Jan 24, 2025

tuunit Jan 23, 2025

yves-chevallier Jan 23, 2025

tuunit Jan 23, 2025

yves-chevallier commented Jan 24, 2025

tuunit commented Jan 25, 2025 •

edited

Loading

yves-chevallier commented Jan 25, 2025

tuunit left a comment

tuunit Jan 25, 2025

tuunit Jan 25, 2025

tuunit Jan 25, 2025

tuunit Jan 25, 2025

tuunit Jan 25, 2025

tuunit Jan 25, 2025

tuunit Jan 25, 2025

tuunit Jan 25, 2025

tuunit Jan 25, 2025

tuunit Jan 25, 2025

		@@ -1,32 +1,41 @@
		<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 host="Electron" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.7.8 Chrome/128.0.6613.36 Electron/32.0.1 Safari/537.36" version="24.7.8">

	<mxfile host="Electron" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.7.8 Chrome/128.0.6613.36 Electron/32.0.1 Safari/537.36" version="24.7.8">
	<mxfile>


		## Usage

		Simply add an image as you would normally do in markdown:

	Simply add an image as you would normally do in markdown:
	Simply add your drawio files like you would any other image in markdown:

		## 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.


		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

	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
	It relies on JGraph's [mxGraph](https://jgraph.github.io/mxgraph/) library to render the diagrams. A mxGraph uses XML to define the structure of diagrams. Here an example


		## 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.

	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.
	The plugin uses the minified version of the [drawio viewer](https://github.com/jgraph/drawio/blob/dev/src/main/webapp/js/viewer-static.min.js).

		@@ -0,0 +1,7 @@
		# Code Blocks

		Diagrams are not rendered in code blocks. So you don't have to worry about the diagram being rendered in the code block.

		poetry = { version = "^2.0", python = ">=3.9" } # Marqueur d'environnement
		black = { version = ">=24.0", python = ">=3.9" } # Pareil pour black

feat: add dynamic theme colors and attr_list support for paging #21

Are you sure you want to change the base?

feat: add dynamic theme colors and attr_list support for paging #21

Conversation

yves-chevallier commented Jan 23, 2025

tuunit left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yves-chevallier commented Jan 24, 2025

tuunit commented Jan 25, 2025 • edited Loading

yves-chevallier commented Jan 25, 2025

tuunit left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tuunit commented Jan 25, 2025 •

edited

Loading