# MkDocs Plugin for embedding Drawio files
[![Publish Badge](https://github.com/tuunit/mkdocs-drawio/workflows/Publish/badge.svg)](https://github.com/tuunit/mkdocs-drawio/actions)
[![PyPI](https://img.shields.io/pypi/v/mkdocs-drawio)](https://pypi.org/project/mkdocs-drawio/)
[Buy Sergey a ☕](https://www.buymeacoffee.com/SergeyLukin)
Sergey ([onixpro](https://github.com/onixpro)) is the original creator of this plugin. Repo can be found [here.](https://github.com/onixpro/mkdocs-drawio-file)
## Features
This plugin enables you to embed interactive drawio diagrams in your documentation. Simply add your diagrams like you would any other image:
```markdown
![](my-diagram.drawio)
```
Additionally this plugin supports multi page diagrams by using the `alt` text to select the pages by name:
```markdown
![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`
```yaml
plugins:
- drawio
```
### Configuration
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.
```yaml
plugins:
- drawio:
viewer_js: "https://viewer.diagrams.net/js/viewer-static.min.js"
```
## 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. Either use the devcontainer or setup a venv with mkdocs installed
2. Install your current local version: `pip install -e .`
3. Add a test for your changes in the `example` directory
4. Test your changes by starting `mkdocs serve` in the `example` directory
5. Increase the version `pyproject.toml` and `setup.py`
6. Open pull request
Raw data
{
"_id": null,
"home_page": "https://github.com/tuunit/mkdocs-drawio/",
"name": "mkdocs-drawio",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.7.0",
"maintainer_email": null,
"keywords": "mkdocs, plugin, markdown, drawio",
"author": "Sergey Lukin",
"author_email": "onixpro@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8f/00/c2707205093e66a969a42d3597f0153cf3283d0fb8f40e5ad4fb9ce47a36/mkdocs_drawio-1.6.1.tar.gz",
"platform": null,
"description": "# MkDocs Plugin for embedding Drawio files\n[![Publish Badge](https://github.com/tuunit/mkdocs-drawio/workflows/Publish/badge.svg)](https://github.com/tuunit/mkdocs-drawio/actions)\n[![PyPI](https://img.shields.io/pypi/v/mkdocs-drawio)](https://pypi.org/project/mkdocs-drawio/)\n\n[Buy Sergey a \u2615](https://www.buymeacoffee.com/SergeyLukin) \n\nSergey ([onixpro](https://github.com/onixpro)) is the original creator of this plugin. Repo can be found [here.](https://github.com/onixpro/mkdocs-drawio-file)\n\n## Features\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\n![](my-diagram.drawio)\n```\n\nAdditionally this plugin supports multi page diagrams by using the `alt` text to select the pages by name:\n\n```markdown\n![Page-2](my-diagram.drawio)\n![my-custom-page-name](my-diagram.drawio)\n```\n\n## Setup\n\nInstall plugin using pip:\n\n```\npip install mkdocs-drawio\n```\n\nAdd the plugin to your `mkdocs.yml`\n\n```yaml\nplugins:\n - drawio\n```\n\n### Configuration\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```yaml\nplugins:\n - drawio:\n viewer_js: \"https://viewer.diagrams.net/js/viewer-static.min.js\"\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\n## Contribution guide\n\n1. Either use the devcontainer or setup a venv with mkdocs installed\n2. Install your current local version: `pip install -e .`\n3. Add a test for your changes in the `example` directory\n4. Test your changes by starting `mkdocs serve` in the `example` directory\n5. Increase the version `pyproject.toml` and `setup.py`\n6. Open pull request\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MkDocs plugin for embedding Drawio files",
"version": "1.6.1",
"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": "",
"digests": {
"blake2b_256": "6e81f08b10e290b1bd21cc68385d76a7286180fe0763b9e6ea97f24f1ae8c40e",
"md5": "8e2a973c16012bb4893d1ce9d7bc41f9",
"sha256": "23089ad911ba406d68ba3106682138fa34740760ade4d7136830c12060304186"
},
"downloads": -1,
"filename": "mkdocs_drawio-1.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8e2a973c16012bb4893d1ce9d7bc41f9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.7.0",
"size": 4776,
"upload_time": "2024-05-07T23:30:27",
"upload_time_iso_8601": "2024-05-07T23:30:27.773494Z",
"url": "https://files.pythonhosted.org/packages/6e/81/f08b10e290b1bd21cc68385d76a7286180fe0763b9e6ea97f24f1ae8c40e/mkdocs_drawio-1.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f00c2707205093e66a969a42d3597f0153cf3283d0fb8f40e5ad4fb9ce47a36",
"md5": "20090dd89a5a39c5a109d8a0e89aad16",
"sha256": "ae1ca4b29f4b15c0a3161329623cfb12e3da1cf68b57682e9c584acc9543ace7"
},
"downloads": -1,
"filename": "mkdocs_drawio-1.6.1.tar.gz",
"has_sig": false,
"md5_digest": "20090dd89a5a39c5a109d8a0e89aad16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.7.0",
"size": 4033,
"upload_time": "2024-05-07T23:30:29",
"upload_time_iso_8601": "2024-05-07T23:30:29.397798Z",
"url": "https://files.pythonhosted.org/packages/8f/00/c2707205093e66a969a42d3597f0153cf3283d0fb8f40e5ad4fb9ce47a36/mkdocs_drawio-1.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-07 23:30:29",
"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"
}