mkdocs-drawio

What it is and what it does

mkdocs-drawio is a MkDocs plugin that transforms .drawio image references in your markdown into interactive, embedded diagram viewers. Instead of static image files, your documentation displays live Drawio diagrams that readers can zoom, pan, interact with, and optionally open in the full editor. The plugin hooks into MkDocs' post-page generation event, scans for .drawio image tags, and replaces them with mxgraph HTML blocks that render the diagram content inline.

The plugin supports multi-page diagrams (selecting specific pages via markdown attributes), custom viewer URLs for air-gapped environments, and integrates with Material theme's instant-loading feature. It depends on requests, jinja2, beautifulsoup4, lxml, and pypng to parse and transform the generated HTML. Configuration options control toolbar visibility, dark mode, lightbox behavior, and diagram interactivity.

Use it for:

• Embed architecture diagrams, flowcharts, or UX wireframes directly in API or technical documentation so readers can interact without downloading files.
• Create multi-page diagram documents where different pages show different views of the same system, selectable within the documentation.
• Set up documentation in air-gapped environments by self-hosting the Drawio viewer JavaScript and configuring a custom viewer URL.
• Enable live diagram editing within documentation sites by toggling the edit option, allowing readers to modify and explore diagrams interactively.
• Integrate diagrams into tabbed documentation layouts using pymdownx.tabbed with the provided JavaScript workaround.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A MkDocs plugin that embeds interactive Drawio diagrams directly into documentation by converting .drawio image references into embedded diagram viewers.

Yes. The plugin is actively maintained, has no known vulnerabilities, installs with low friction, and solves a real problem for documentation sites that need interactive diagrams. MIT licensing removes legal friction. Install it if your MkDocs project needs embedded Drawio diagrams; the dependency footprint is small and the setup is straightforward.

Install

mkdocs-drawio on PyPI

pip install mkdocs-drawio

uv add mkdocs-drawio

poetry add mkdocs-drawio

Installing mkdocs-drawio

Before you install

Low friction installation as a pure Python wheel. Actively maintained with a recent release; repository shows 46 stars and was last updated 2026-07-25. Requires Python 3.9 or newer and depends on common, well-established packages (requests, jinja2, beautifulsoup4, lxml, mkdocs, pypng).

License in practice

MIT license is permissive, allowing use in commercial and private projects with minimal restrictions.

Quickstart

pip install mkdocs-drawio

Then add to mkdocs.yml:
plugins:
  - drawio

In markdown:
![My Diagram](diagram.drawio)
![Page 2](diagram.drawio){ page="Page-2" }

Requires Python 3.9 or newer and an active MkDocs project with mkdocs.yml configuration.

Verify before relying

• Whether the plugin works with all MkDocs themes or only specific ones (Material theme integration is documented, but compatibility with others is unclear).
• Performance impact when embedding many diagrams or large .drawio files in a single documentation site.

Package facts

Evidence: mkdocs_drawio-1.16.3-py3-none-any.whl

Keywords: mkdocs, plugin, markdown, drawio

Tags

More Documentation packages