mkdocs-bpmn-js

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.

Installation

Install via pip:

pip install mkdocs-bpmn-js

Then enable the plugin in your mkdocs.yml:

plugins:
  - bpmn-js

Plugin Options

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"

Option	Description	Default Value
render	Specify the render mode (none, image, viewer).	viewer
class	CSS class applied to each diagram container.	mk-bpmn-js
viewer_js	URL to the BPMN viewer JavaScript file.	https://unpkg.com/bpmn-js@18/dist/bpmn-navigated-viewer.production.min.js
viewer_css	URL to the BPMN viewer CSS file.	https://unpkg.com/bpmn-js@18/dist/assets/bpmn-js.css
viewer_initialize	Append a script to load the diagrams.	True
image_command	Command to call when render is set to image.	bpmn-to-image --no-title --no-footer $input:$output

Local viewer assets

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: ""

Image rendering

To render an image instead of an interactive viewer, set the render config to image. We recommend using bpmn-to-image, but you can use any script you prefer. During rendering, the plugin will call the image_command and replace $input with the absolute path to the BPMN diagram and $output with a temporary cache file.

For example, with the default image_command:

image_command: "bpmn-to-image --no-title --no-footer $input:$output"

Have a look at the example to see how bpmn-to-image can be configured and used.

Usage

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.

Diagram Options

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)

Parameter	Description	Example
id	Sets the HTML id of the viewer canvas. Useful for linking.	id=my-diagram
width	Sets the diagram width. Accepts any valid CSS width value.	width=100%25
height	Sets the diagram height. Accepts any valid CSS height value.	height=300px

Acknowledgments

• 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.