MkDocs plugin for embedding Drawio files
Project description
MkDocs Plugin for embedding Drawio files
Sergey (onixpro) is the original creator of this plugin. Repo can be found here.
Features
This plugin enables you to embed interactive drawio diagrams in your documentation. Simply add your diagrams like you would any other image:
You can either use diagrams hosted within your own docs. Absolute as well as relative paths are allowed:
Absolute path:
![](/assets/my-diagram.drawio)
Same directory as the markdown file:
![](my-diagram.drawio)
Relative directory to the markdown file:
![](../my-diagram.drawio)
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:
![Page-2](my-diagram.drawio)
![my-custom-page-name](my-diagram.drawio)
Setup
Install plugin using pip:
pip install mkdocs-drawio
Add the plugin to your mkdocs.yml
plugins:
- drawio
Configuration Options
By default the plugin uses the official url for the minified drawio javascript library. To use a custom source for the drawio viewer you can overwritte the url. This might be useful in airlocked environments.
If you want to use a self-hosted JavaScript viewer file. You should download the latest version from the official drawio repo.
plugins:
- drawio:
viewer_js: "https://viewer.diagrams.net/js/viewer-static.min.js"
Further options are:
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)
border: 10 # increase or decrease the border / margin around your diagrams (default: 5)
Material Integration
If you are using the Material Theme and want to use the instant-loading feature. You will have to configure the following:
In your mkdocs.yaml
:
theme:
name: material
features:
- navigation.instant
plugins:
- drawio
extra_javascript:
- https://viewer.diagrams.net/js/viewer-static.min.js
- javascripts/drawio-reload.js
Add docs/javascripts/drawio-reload.js
to your project:
document$.subscribe(({ body }) => {
GraphViewer.processElements()
})
How it works
- mkdocs generates the html per page
mkdocs-drawio
attaches to theon_post_page
event. For more details, please have a look at the event lifecycle documentation- Adds the drawio viewer library
- Searches through the generated html for all
img
tags that have a source of type.drawio
- Replaces the found
img
tags withmxgraph
html blocks (actual drawio diagram content). For more details, please have a look at the official drawio.com documentation.
Contribution guide
- Either use the devcontainer or setup a venv with mkdocs installed
- Install your current local version:
pip install -e .
- Add a test for your changes in the
example
directory - Test your changes by starting
mkdocs serve
in theexample
directory - Increase the version
pyproject.toml
- Open pull request
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_drawio-1.7.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 31d5f672ccb5b6c6aaaafc2d4c0e6bdb33981dbea2dd70dae9cea163d612b304 |
|
MD5 | 970e8aa1d6a37650c5e6952ab95975a6 |
|
BLAKE2b-256 | 1427f4a58ffa1d9b88e345bc5a23006b563c0707406a8411a61a87a750bfdfe5 |