---
id: mkdocs-drawio
version: "1.16.3"
license: MIT
license_treatment: permissive
maintenance: active
---

# mkdocs-drawio — MkDocs plugin for embedding Drawio files

License: permissive · Maintenance: active · Downloads: 160.1K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 160.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs diagram embedding, drawio markdown plugin, interactive diagrams documentation, mkdocs visualization plugin, embed drawio files, diagram viewer markdown, mkdocs-plugin, diagram-embedding

[View on SkillFed](https://skillfed.io/packages/mkdocs-drawio) · [View on PyPI](https://pypi.org/project/mkdocs-drawio/)