# mkdocs-bpmn-js
**mkdocs-bpmn-js** is a simple MkDocs plugin that enables you to embed [BPMN diagrams](https://en.wikipedia.org/wiki/Business_Process_Model_and_Notation) directly into your documentation using [`bpmn-js`](https://bpmn.io/toolkit/bpmn-js/). Diagrams are embedded just like images, using Markdown syntax.
## Installation
Install via pip:
```bash
pip install mkdocs-bpmn-js
```
Then enable the plugin in your `mkdocs.yml`:
```yaml
plugins:
- bpmn-js
```
### Plugin Options
You can configure the plugin by adding options under `bpmn-js` in `mkdocs.yml`.
```yaml
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.
```bash
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](https://www.mkdocs.org/user-guide/customizing-your-theme/#overriding-template-blocks) for more details.
```html
{% 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`:
```yaml
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](https://github.com/bpmn-io/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`:
```yaml
image_command: "bpmn-to-image --no-title --no-footer $input:$output"
```
Have a look at the [example](./example/mkdocs.yml) to see how `bpmn-to-image` can be configured and used.
## Usage
Add `.bpmn` files using standard Markdown image syntax:
```markdown
<!-- Relative path to the current Markdown file -->
<!-- Absolute path from the site root -->
<!-- No alternative text -->
<!-- With diagram options (see below for more details) -->
```
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.
```markdown
```
| 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](https://github.com/tuunit/mkdocs-drawio), which served as a helpful reference for embedding diagrams in MkDocs.
- Also check out [mkdocs-bpmn](https://github.com/vanchaxy/mkdocs-bpmn), an alternative implementation. Depending on your needs, it might be a better fit.
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-bpmn-js",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "bpmn, bpmn-js, mkdocs, plugin",
"author": "Christian Schuhmann",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/dd/ca/c2cd59c782dcd456f023aec1ccf97e42219ed142241df75102c25697b5b2/mkdocs_bpmn_js-0.2.0.tar.gz",
"platform": null,
"description": "# mkdocs-bpmn-js\n\n**mkdocs-bpmn-js** is a simple MkDocs plugin that enables you to embed [BPMN diagrams](https://en.wikipedia.org/wiki/Business_Process_Model_and_Notation) directly into your documentation using [`bpmn-js`](https://bpmn.io/toolkit/bpmn-js/). Diagrams are embedded just like images, using Markdown syntax.\n\n## Installation\n\nInstall via pip:\n\n```bash\npip install mkdocs-bpmn-js\n```\n\nThen enable the plugin in your `mkdocs.yml`:\n\n```yaml\nplugins:\n - bpmn-js\n```\n\n### Plugin Options\n\nYou can configure the plugin by adding options under `bpmn-js` in `mkdocs.yml`.\n\n```yaml\nplugins:\n - bpmn-js:\n viewer_js: \"https://unpkg.com/bpmn-js@18/dist/bpmn-navigated-viewer.production.min.js\"\n viewer_css: \"https://unpkg.com/bpmn-js@18/dist/assets/bpmn-js.css\"\n class: \"mk-bpmn-js\"\n```\n\n| Option | Description | Default Value |\n| ------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------- |\n| `render` | Specify the render mode (`none`, `image`, `viewer`). | `viewer` |\n| `class` | CSS class applied to each diagram container. | `mk-bpmn-js` |\n| `viewer_js` | URL to the BPMN viewer JavaScript file. | `https://unpkg.com/bpmn-js@18/dist/bpmn-navigated-viewer.production.min.js` |\n| `viewer_css` | URL to the BPMN viewer CSS file. | `https://unpkg.com/bpmn-js@18/dist/assets/bpmn-js.css` |\n| `viewer_initialize` | Append a script to load the diagrams. | `True` |\n| `image_command` | Command to call when `render` is set to `image`. | `bpmn-to-image --no-title --no-footer $input:$output` |\n\n### Local viewer assets\n\nIf you prefer not to load assets from a CDN, you can host the required BPMN viewer files yourself.\n\n```bash\nmkdir -p theme/js theme/css\ncurl -L https://unpkg.com/bpmn-js@18/dist/bpmn-navigated-viewer.production.min.js > theme/js/bpmn.js\ncurl -L https://unpkg.com/bpmn-js@18/dist/assets/bpmn-js.css > theme/css/bpmn.css\n```\n\nOverride the default theme to include your local assets by creating a custom `theme/main.html` template.\nRefer to the [MkDocs guide on customizing themes](https://www.mkdocs.org/user-guide/customizing-your-theme/#overriding-template-blocks) for more details.\n\n```html\n{% extends \"base.html\" %} {% block styles %} {{ super() }}\n<link rel=\"stylesheet\" href=\"{{ base_url }}/css/bpmn.css\" />\n{% endblock %} {% block libs %} {{ super() }}\n<script src=\"{{ base_url }}/js/bpmn.js\"></script>\n{% endblock %}\n```\n\nFinally, disable the default CDN links by setting the plugin options to empty strings in `mkdocs.yml`:\n\n```yaml\nplugins:\n - bpmn-js:\n viewer_js: \"\"\n viewer_css: \"\"\n```\n\n### Image rendering\n\nTo render an image instead of an interactive viewer, set the `render` config to `image`. We recommend using [bpmn-to-image](https://github.com/bpmn-io/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.\n\nFor example, with the default `image_command`:\n\n```yaml\nimage_command: \"bpmn-to-image --no-title --no-footer $input:$output\"\n```\n\nHave a look at the [example](./example/mkdocs.yml) to see how `bpmn-to-image` can be configured and used.\n\n## Usage\n\nAdd `.bpmn` files using standard Markdown image syntax:\n\n```markdown\n<!-- Relative path to the current Markdown file -->\n\n\n\n<!-- Absolute path from the site root -->\n\n\n\n<!-- No alternative text -->\n\n\n\n<!-- With diagram options (see below for more details) -->\n\n\n```\n\nThe alternative text is optional and will be rendered as a link to the diagram file within a `noscript` element.\n\n### Diagram Options\n\nYou can customize individual diagrams using query parameters in the image URL.\n\n```markdown\n\n```\n\n| Parameter | Description | Example |\n| --------- | ------------------------------------------------------------ | --------------- |\n| `id` | Sets the HTML `id` of the viewer canvas. Useful for linking. | `id=my-diagram` |\n| `width` | Sets the diagram width. Accepts any valid CSS width value. | `width=100%25` |\n| `height` | Sets the diagram height. Accepts any valid CSS height value. | `height=300px` |\n\n## Acknowledgments\n\n- Inspired by [mkdocs-drawio](https://github.com/tuunit/mkdocs-drawio), which served as a helpful reference for embedding diagrams in MkDocs.\n- Also check out [mkdocs-bpmn](https://github.com/vanchaxy/mkdocs-bpmn), an alternative implementation. Depending on your needs, it might be a better fit.\n",
"bugtrack_url": null,
"license": null,
"summary": "MkDocs plugin for embedding BPMN files via bpmn-js",
"version": "0.2.0",
"project_urls": {
"Repository": "https://github.com/madebyherzblut/mkdocs-bpmn-js"
},
"split_keywords": [
"bpmn",
" bpmn-js",
" mkdocs",
" plugin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a0d99a20109923779da7733ce871707063a13134e29884592dac45dd422f8f6d",
"md5": "6c64071cb67faa5b133a3a254dae3aa4",
"sha256": "4b4cff329cbdba0aba853463f3e10f4f7316874bda56b6abbca0d5cdc049d534"
},
"downloads": -1,
"filename": "mkdocs_bpmn_js-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c64071cb67faa5b133a3a254dae3aa4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6848,
"upload_time": "2025-08-01T18:15:49",
"upload_time_iso_8601": "2025-08-01T18:15:49.202322Z",
"url": "https://files.pythonhosted.org/packages/a0/d9/9a20109923779da7733ce871707063a13134e29884592dac45dd422f8f6d/mkdocs_bpmn_js-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ddcac2cd59c782dcd456f023aec1ccf97e42219ed142241df75102c25697b5b2",
"md5": "8bbfd32985f827eafc76cea73e9f3056",
"sha256": "5c9b7ece2b96cd136af9400adc79eac71e0d048857d44e38fdaffe7111dbda64"
},
"downloads": -1,
"filename": "mkdocs_bpmn_js-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "8bbfd32985f827eafc76cea73e9f3056",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 39332,
"upload_time": "2025-08-01T18:15:50",
"upload_time_iso_8601": "2025-08-01T18:15:50.302326Z",
"url": "https://files.pythonhosted.org/packages/dd/ca/c2cd59c782dcd456f023aec1ccf97e42219ed142241df75102c25697b5b2/mkdocs_bpmn_js-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 18:15:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "madebyherzblut",
"github_project": "mkdocs-bpmn-js",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-bpmn-js"
}
JSON
