Skip to main content

MkDocs plugin for embedding Drawio files

Project description

MkDocs Plugin for embedding Drawio files

Publish Badge PyPI

Buy Sergey a ☕

Sergey (onixpro) is the original creator of this plugin. Repo can be found here.

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 the alt text to select the pages by name:

![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

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)
      border: 10     # increase or decrease the border / margin around your diagrams (default: 5) 

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. 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
  6. Open pull request

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_drawio-1.7.0.tar.gz (4.7 kB view details)

Uploaded Source

Built Distribution

mkdocs_drawio-1.7.0-py3-none-any.whl (5.4 kB view details)

Uploaded Python 3

File details

Details for the file mkdocs_drawio-1.7.0.tar.gz.

File metadata

  • Download URL: mkdocs_drawio-1.7.0.tar.gz
  • Upload date:
  • Size: 4.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for mkdocs_drawio-1.7.0.tar.gz
Algorithm Hash digest
SHA256 8edb3a3b348a33d3ede722b5e93e1104c89904c3b510749f98cb8ac0ff1ed7f7
MD5 0eb7592e616101ad85817e6c9193f6cc
BLAKE2b-256 f6d6dc8617e9abd626f5b22cea389166193452cee8292fcab63b0cf01897831f

See more details on using hashes here.

File details

Details for the file mkdocs_drawio-1.7.0-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_drawio-1.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 31d5f672ccb5b6c6aaaafc2d4c0e6bdb33981dbea2dd70dae9cea163d612b304
MD5 970e8aa1d6a37650c5e6952ab95975a6
BLAKE2b-256 1427f4a58ffa1d9b88e345bc5a23006b563c0707406a8411a61a87a750bfdfe5

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page