mkdocs-bpmn-js is a simple MkDocs plugin that enables you to embed BPMN diagrams directly into your documentation using bpmn-js. Diagrams are embedded just like images, using Markdown syntax.

Install via pip:

pip install mkdocs-bpmn-js

Then enable the plugin in your mkdocs.yml:

plugins:
  - bpmn-js

You can configure the plugin by adding options under bpmn-js in mkdocs.yml.

plugins:
  - bpmn-js:
      viewer_js: "https://unpkg.com/bpmn-js@18/dist/bpmn-navigated-viewer.production.min.js"
      viewer_css: "https://unpkg.com/bpmn-js@18/dist/assets/bpmn-js.css"
      class: "mk-bpmn-js"

If you prefer not to load assets from a CDN, you can host the required BPMN viewer files yourself.

mkdir -p theme/js theme/css
curl -L https://unpkg.com/bpmn-js@18/dist/bpmn-navigated-viewer.production.min.js > theme/js/bpmn.js
curl -L https://unpkg.com/bpmn-js@18/dist/assets/bpmn-js.css > theme/css/bpmn.css

Override the default theme to include your local assets by creating a custom theme/main.html template. Refer to the MkDocs guide on customizing themes for more details.

{% extends "base.html" %}
{% block styles %}
  {{ super() }}
  <link rel="stylesheet" href="{{ base_url }}/css/bpmn.css" />
{% endblock %}
{% block libs %}
  {{ super() }}
  <script src="{{ base_url }}/js/bpmn.js"></script>
{% endblock %}

Finally, disable the default CDN links by setting the plugin options to empty strings in mkdocs.yml:

plugins:
  - bpmn-js:
      viewer_js: ""
      viewer_css: ""

Add .bpmn files using standard Markdown image syntax:

<!-- Relative path to the current Markdown file -->
![Hello World](hello-world.bpmn)
<!-- Absolute path from the site root -->
![Hello World](/diagrams/hello-world.bpmn)
<!-- No alternative text -->
![](hello-world.bpmn)
<!-- With diagram options (see below for more details) -->
![](hello-world.bpmn?id=hello-world&height=400px)

The alternative text is optional and will be rendered as a link to the diagram file within a noscript element.

You can customize individual diagrams using query parameters in the image URL.

![Custom Diagram](my-diagram.bpmn?id=my-diagram&height=500px&width=100%25)

• Inspired by mkdocs-drawio, which served as a helpful reference for embedding diagrams in MkDocs.
• Also check out mkdocs-bpmn, an alternative implementation. Depending on your needs, it might be a better fit.