mkdocs-drawio 1.13.0
MkDocs plugin for embedding Drawio files
License: MIT
Requires Python: <4.0,>=3.8.0
Keywords: mkdocs, plugin, markdown, drawio

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

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:
![](/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`.

```markdown
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:

```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:
      tooltips: true       # Enable tooltips on diagram elements
      border: 5            # Border size / padding around diagrams
      edit: true           # Enable opening the editor for diagrams
      darkmode: true       # Enable dark mode support (classic MkDocs and Material)
      highlight: "#0000FF" # Highlight color for hyperlinks
      lightbox: true       # Enable opening the lightbox on click
      toolbar:             # Control the looks and behaviour of the toolbar
        pages: true        # Display the page selector
        tags: true         # Display the tags selector
        zoom: true         # Display the zoom controls
        layers: true       # Display the layer controls
        lightbox: true     # Display the lightbox / fullscreen button
        position: "top"    # Control the position of the toolbar (top or bottom)
        no_hide: false     # Do not hide the toolbar when not hovering over diagrams
```

## 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()
})
```

## Using Tabs (pymdownx.tabbed)

If you want to use drawio diagrams inside of tabs you need to make sure that the diagrams are processed after the tabs are rendered. You can achieve this by adding the following javascript to your `mkdocs.yml`:

```yaml
extra_javascript:
  - javascripts/drawio-tabs.js
```

Add `docs/javascripts/drawio-tabs.js` to your project:

```js
document.addEventListener('change', (event) => {
  // Check if the target is a pymdownx tab input
  if (event.target.matches('.tabbed-set > input')) {
    GraphViewer.processElements()
  }
});
```

Its a bit of a workaround as it listens for all events on the page and retriggers the drawio processing if any tab is clicked.


## 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 ✨️