https://github.com/foliant-docs/foliantcontrib.bpmn
BPMN diagrams preprocessor for Foliant
https://github.com/foliant-docs/foliantcontrib.bpmn
Last synced: 5 months ago
JSON representation
BPMN diagrams preprocessor for Foliant
- Host: GitHub
- URL: https://github.com/foliant-docs/foliantcontrib.bpmn
- Owner: foliant-docs
- License: mit
- Created: 2021-08-02T10:38:17.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-08-02T14:13:53.000Z (almost 5 years ago)
- Last Synced: 2025-09-13T17:38:22.504Z (9 months ago)
- Language: Python
- Size: 5.86 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pypi.org/project/foliantcontrib.bpmn/) [](https://github.com/foliant-docs/foliantcontrib.bpmn)
# BPMN Diagrams Preprocessor for Foliant
[BPMN (Business Process Modeling Notation)](https://www.bpmn.org/) is visual modeling language for documenting business workflows. This preprocessor converts BPMN diagram definitions in source markdown files and converts them into images on the fly during project build.
This preprocessor uses [bpmn-to-image](https://github.com/bpmn-io/bpmn-to-image) tool by [bpmn.io](https://bpmn.io/) to convert diagrams into images.
## Installation
```bash
$ pip install foliantcontrib.bpmn
```
You will also need to install bpmn-to-image:
```bash
$ npm install -g bpmn-to-image
```
## Config
To enable the preprocessor, add `bpmn` to `preprocessors` section in the project config:
```yaml
preprocessors:
- bpmn
```
The preprocessor has a number of options:
```yaml
preprocessors:
- bpmn:
cache_dir: !path .diagramscache/bpmn
converter_path: bpmn-to-image
format: png
as_image: true
params:
no-title: true
`fix_svg_size`: false
```
`cache_dir`
: Path to the cache directory for the generated diagrams. It can be a path relative to the project root or a global one.
> To save time during build, only new and modified diagrams are rendered. The generated images are cached and reused in future builds.
`converter_path`
: Path to bpmn-to-image binary. By default, it is assumed that you have the `bpmn-to-image` command in your `PATH`, but if it is not the case you can define it here. Default: `bpmn-to-image`
`format`
: Output format of the diagram image. [Available formats](https://github.com/bpmn-io/bpmn-to-image) at the time of writing: `pdf`, `png`, `svg` (note that most backends won't render `pdf` as image). Default: `png`
`as_image`
: If `true` — inserts the diagram into the document as Markdown-image. If `false` — inserts the svg code of the diagram directly into the document (works only for `svg` format). Default: `true`
`params`
: Params passed to the bpmn-to-image tool. Value of this option must be a YAML-mapping. Params which require values should be specified as `param: value`; params which don't require values should be specified as `param: true`:
preprocessors:
- bpmn:
params:
no-footer: true
min-dimensions: '500x300'
> To see the full list of available params, run the `bpmn-to-image` command without parameters.
`fix_svg_size`
: Works only with `svg` format and `as_image: false`. By default svg is embedded with hardcoded width and height so they may exceed the boundaries of your HTML page. If this option is set to `true` the svg width and height will be set to `100%` which will make it fit inside your content container. Default: `false`.
## Usage
To insert a diagram definition in your Markdown source, enclose it between `...` tags:
```html
Here’s the diagram:
```
You can override preprocessor parameters in the tag options. For example if the format for diagrams is set to `png` in foliant.yml and you need one of your diagrams to render in svg, override the `format` option in the tag:
```html
SVG diagram:
...
```
Tags also have an exclusive option `caption` — the markdown caption of the diagram image.
```html
Diagram with a caption:
...
```