MkDocs Plugin for embedding Drawio files

Sergey (onixpro) is the original creator of this plugin but since his repository isn't maintained anymore we forked it on the 19th December of 2023 and have been keeping it up-to-date and expanding on the features since then. Buy Sergey a ☕

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 either the page or alt property. To use the page property, you need to use the markdown extension attr_list.

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:

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

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

1. mkdocs generates the html per page
2. mkdocs-drawio attaches to the on_post_page event. For more details, please have a look at the event lifecycle documentation
3. Adds the drawio viewer library
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.

Contribution guide

1. Setup a virtual environment: python3 -m venv venv && source venv/bin/activate
2. Install poetry: pip install poetry
3. Install dependencies and current version: poetry install
4. Make your desired changes
5. Add a test for your changes in the example directory
6. Test your changes by starting mkdocs serve in the example directory
7. Increase the version in pyproject.toml
8. Make sure poetry run ruff check . and poetry run black --check . passing
9. Open your pull request ✨️