MkDocs Draw.io Plugin

1.15.0 verified Mon Apr 27 auth: no python

MkDocs plugin for embedding Draw.io (diagrams.net) diagrams in your documentation. It supports .drawio, .dio, and .drawio.svg files, with features like dark mode, custom toolbars, and page navigation. Current version: 1.15.0, actively maintained with regular releases.

pip install mkdocs-drawio

Common errors

error ERROR - Config value: 'plugins'. Error: The "drawio" plugin is not installed. ↓

cause mkdocs-drawio pip package not installed in the environment.

fix

Run pip install mkdocs-drawio and ensure the Python environment is active.

error ValueError: Unrecognised configuration key: 'drawio-file' ↓

cause Using the old plugin name 'drawio-file' instead of 'drawio'.

fix

In mkdocs.yml, change plugins: [drawio-file] to plugins: [drawio].

error FileNotFoundError: [Errno 2] No such file: 'diagram.drawio' ↓

cause Diagram file not found in the docs directory or path is incorrect.

fix

Verify the .drawio file exists inside the docs folder and the Markdown image path is relative to the docs root (e.g., ![Diagram](images/diagram.drawio)).

error lxml.etree.XMLSyntaxError: ... ↓

cause The .drawio file is corrupted or not a valid XML.

fix

Re-save the diagram from Draw.io to ensure proper XML format.

Warnings

breaking MkDocs 1.6+ has breaking changes in plugin APIs; older versions of mkdocs-drawio may not work. Upgrade to at least v1.12.0 for MkDocs 1.6 support. ↓

fix Update to mkdocs-drawio >= 1.12.0.

gotcha Diagram files must be placed inside the docs directory. Files outside will not be processed. ↓

fix Move .drawio files into your docs folder (or a subfolder).

deprecated The old `drawio-file` configuration key is deprecated in favor of `drawio` in mkdocs.yml. ↓

fix Use `plugins: [drawio]` instead of `plugins: [drawio-file]`.

gotcha Dark mode requires the drawio toolbox to have the 'dark mode' option enabled. It does not automatically match the browser/system theme. ↓

fix Add `dark_mode: true` under the drawio plugin configuration in mkdocs.yml.

Imports

mkdocs_drawio
wrong
```
import mkdocs_drawio
```
correct
```
mkdocs_drawio (imported automatically as MkDocs plugin)
```
This is a MkDocs plugin, not a Python module to import directly. It is configured in mkdocs.yml.

Quickstart

Add the drawio plugin to your MkDocs configuration. Then place .drawio files in your docs directory and reference them with standard Markdown image syntax like `![Diagram](diagram.drawio)`.

# mkdocs.yml
plugins:
  - drawio