# MkDocs Plugin for embedding Drawio files
[](https://github.com/tuunit/mkdocs-drawio/actions)
[](https://pypi.org/project/mkdocs-drawio/)
Sergey ([onixpro](https://github.com/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 ☕](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
You can either use diagrams hosted within your own docs. Absolute as well as relative paths are allowed:
Absolute path:
Same directory as the markdown file:
Relative directory to the markdown file:
Or you can use external urls:
```
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
```
Add the plugin to your `mkdocs.yml`
```yaml
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](https://github.com/jgraph/drawio/blob/dev/src/main/webapp/js/viewer-static.min.js).
```yaml
plugins:
- drawio:
viewer_js: "https://viewer.diagrams.net/js/viewer-static.min.js"
```
Further options are:
```yaml
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)
highlight: "#0000FF" # color hyperlinks on mouse hover over (default: no color)
```
## Material Integration
If you are using the Material Theme and want to use the [instant-loading](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=instant#instant-loading) feature. You will have to configure the following:
In your `mkdocs.yaml`:
```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:
```js
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](https://www.mkdocs.org/dev-guide/plugins/#events)
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](https://www.drawio.com/doc/faq/embed-html).
## 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 ✨️
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-drawio",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8.0",
"maintainer_email": null,
"keywords": "mkdocs, plugin, markdown, drawio",
"author": "Jan Larwig",
"author_email": "jan@larwig.com",
"download_url": "https://files.pythonhosted.org/packages/93/f5/25f717145f5dfea77cde4770c72f5e9c2fb8955c604770ef936bc67f1fa7/mkdocs_drawio-1.12.0.tar.gz",
"platform": null,
"description": "# MkDocs Plugin for embedding Drawio files\n\n[](https://github.com/tuunit/mkdocs-drawio/actions)\n[](https://pypi.org/project/mkdocs-drawio/)\n\nSergey ([onixpro](https://github.com/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. \n[Buy Sergey a \u2615](https://www.buymeacoffee.com/SergeyLukin) \n\n## Features\n\nThis plugin enables you to embed interactive drawio diagrams in your documentation. Simply add your diagrams like you would any other image:\n\n```markdown\nYou can either use diagrams hosted within your own docs. Absolute as well as relative paths are allowed:\n\nAbsolute path:\n\n\nSame directory as the markdown file:\n\n\nRelative directory to the markdown file:\n\n\n\nOr you can use external urls:\n\n```\n\nAdditionally 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`.\n\n```markdown\nEither use the alt text:\n\n\n\nOr use the page attribute:\n{ page=\"Page-2\" }\n{ page=\"my-custom-page-name\" }\n```\n\n## Setup\n\nInstall plugin using pip:\n\n```bash\npip install mkdocs-drawio\n```\n\nAdd the plugin to your `mkdocs.yml`\n\n```yaml\nplugins:\n - drawio\n```\n\n## Configuration Options\n\nBy 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.\n\n> If you want to use a self-hosted JavaScript viewer file. You should download the latest version from the [official drawio repo](https://github.com/jgraph/drawio/blob/dev/src/main/webapp/js/viewer-static.min.js).\n\n```yaml\nplugins:\n - drawio:\n viewer_js: \"https://viewer.diagrams.net/js/viewer-static.min.js\"\n```\n\nFurther options are:\n\n```yaml\nplugins:\n - drawio:\n toolbar: true # control if hovering on a diagram shows a toolbar for zooming or not (default: true)\n tooltips: true # control if tooltips will be shown (default: true)\n edit: true # control if edit button will be shown in the lightbox view (default: true)\n border: 10 # increase or decrease the border / margin around your diagrams (default: 0)\n darkmode: true # support darkmode. allows for automatic switching between dark and lightmode based on the theme toggle. (default: false)\n highlight: \"#0000FF\" # color hyperlinks on mouse hover over (default: no color)\n```\n\n## Material Integration\n\nIf you are using the Material Theme and want to use the [instant-loading](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=instant#instant-loading) feature. You will have to configure the following:\n\nIn your `mkdocs.yaml`:\n\n```yaml\ntheme:\n name: material\n features:\n - navigation.instant\n\nplugins:\n - drawio\n\nextra_javascript:\n - https://viewer.diagrams.net/js/viewer-static.min.js\n - javascripts/drawio-reload.js\n```\n\nAdd `docs/javascripts/drawio-reload.js` to your project:\n\n```js\ndocument$.subscribe(({ body }) => {\n GraphViewer.processElements()\n})\n```\n\n## How it works\n\n1. mkdocs generates the html per page\n2. `mkdocs-drawio` attaches to the `on_post_page` event. For more details, please have a look at the [event lifecycle documentation](https://www.mkdocs.org/dev-guide/plugins/#events)\n3. Adds the drawio viewer library\n4. Searches through the generated html for all `img` tags that have a source of type `.drawio`\n5. 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).\n\n## Contribution guide\n\n1. Setup a virtual environment: `python3 -m venv venv && source venv/bin/activate`\n2. Install poetry: `pip install poetry`\n3. Install dependencies and current version: `poetry install`\n4. Make your desired changes\n5. Add a test for your changes in the `example` directory\n6. Test your changes by starting `mkdocs serve` in the `example` directory\n7. Increase the version in `pyproject.toml`\n8. Make sure `poetry run ruff check .` and `poetry run black --check .` passing\n9. Open your pull request \u2728\ufe0f\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MkDocs plugin for embedding Drawio files",
"version": "1.12.0",
"project_urls": {
"Homepage": "https://github.com/tuunit/mkdocs-drawio/",
"Repository": "https://github.com/tuunit/mkdocs-drawio/"
},
"split_keywords": [
"mkdocs",
" plugin",
" markdown",
" drawio"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "455872af6179952ffeeb5765e54de7adbd7de73c04474ade66b83f6e5e94890a",
"md5": "e97240154e7c763bf326e5a17bc0b8fa",
"sha256": "66fa319c6acc33f5cef96e7c0b9bb1705f6dc9ce02267d2095749778877d608a"
},
"downloads": -1,
"filename": "mkdocs_drawio-1.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e97240154e7c763bf326e5a17bc0b8fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8.0",
"size": 7294,
"upload_time": "2025-10-14T15:37:44",
"upload_time_iso_8601": "2025-10-14T15:37:44.650359Z",
"url": "https://files.pythonhosted.org/packages/45/58/72af6179952ffeeb5765e54de7adbd7de73c04474ade66b83f6e5e94890a/mkdocs_drawio-1.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "93f525f717145f5dfea77cde4770c72f5e9c2fb8955c604770ef936bc67f1fa7",
"md5": "1f09b5162513b44ce238f261a92d2b7f",
"sha256": "4958594838f0f83acb27160c51551e193c130638d29991ac4fa12aecc54548f4"
},
"downloads": -1,
"filename": "mkdocs_drawio-1.12.0.tar.gz",
"has_sig": false,
"md5_digest": "1f09b5162513b44ce238f261a92d2b7f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8.0",
"size": 5845,
"upload_time": "2025-10-14T15:37:46",
"upload_time_iso_8601": "2025-10-14T15:37:46.158680Z",
"url": "https://files.pythonhosted.org/packages/93/f5/25f717145f5dfea77cde4770c72f5e9c2fb8955c604770ef936bc67f1fa7/mkdocs_drawio-1.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 15:37:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tuunit",
"github_project": "mkdocs-drawio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-drawio"
}
JSON
