Foliant的BPMN图预处理器

BPMN（业务流程建模符号）是用于记录业务工作流的可视化建模语言。该预处理器转换源 Markdown 文件中的 BPMN 图定义，并在项目构建期间将它们动态转换为图像。

该预处理器使用bpmn.io的 bpmn-to-image工具将图表转换为图像。

安装

$ pip install foliantcontrib.bpmn

您还需要安装 bpmn-to-image：

$ npm install -g bpmn-to-image

配置

要启用预处理器，请添加bpmn到preprocessors项目配置中的部分：

preprocessors:
    - bpmn

预处理器有许多选项：

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 ：生成图表的缓存目录的路径。它可以是相对于项目根目录的路径，也可以是全局路径。

为了在构建过程中节省时间，仅呈现新的和修改的图表。生成的图像被缓存并在未来的构建中重复使用。

converter_path : bpmn-to-image 二进制文件的路径。默认情况下，假定您的 中包含该bpmn-to-image命令PATH，但如果不是，您可以在此处定义它。默认：bpmn-to-image

format ：图表图像的输出格式。撰写本文时可用的格式pdf： , png, svg（请注意，大多数后端不会呈现pdf为图像）。默认：png

as_image : If true— 将图表作为 Markdown-image 插入到文档中。If false— 将图表的 svg 代码直接插入到文档中（仅适用于svg格式）。默认：true

params : 传递给 bpmn-to-image 工具的参数。此选项的值必须是 YAML 映射。需要值的参数应指定为param: value；不需要值的参数应指定为param: true：

    preprocessors:
        - bpmn:
            params:
                no-footer: true
                min-dimensions: '500x300'

要查看可用参数的完整列表，请运行bpmn-to-image不带参数的命令。

fix_svg_size : 仅适用于svg格式和as_image: false. 默认情况下，svg 嵌入了硬编码的宽度和高度，因此它们可能会超出 HTML 页面的边界。如果此选项设置为truesvg 宽度和高度，则将设置为100%使其适合您的内容容器。默认值：false。

用法

要在 Markdown 源中插入图表定义，请将其括在<bpmn>...</bpmn>标签之间：

Here’s the diagram:

<bpmn>
    <?xml version="1.0" encoding="UTF-8"?>
    <definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:omgdc="http://www.omg.org/spec/DD/20100524/DC" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="sid-38422fae-e03e-43a3-bef4-bd33b32041b2" targetNamespace="http://bpmn.io/bpmn" exporter="http://bpmn.io" exporterVersion="0.10.1">
      <process id="Process_1" isExecutable="false">
        <task id="Task_0l0q2kz" name="Single Task" />
      </process>
      <bpmndi:BPMNDiagram id="BpmnDiagram_1">
        <bpmndi:BPMNPlane id="BpmnPlane_1" bpmnElement="Process_1">
          <bpmndi:BPMNShape id="Task_0l0q2kz_di" bpmnElement="Task_0l0q2kz">
            <omgdc:Bounds x="206" y="108" width="100" height="80" />
          </bpmndi:BPMNShape>
        </bpmndi:BPMNPlane>
      </bpmndi:BPMNDiagram>
    </definitions>
</bpmn>

您可以覆盖标签选项中的预处理器参数。例如，如果图表的格式设置为pngfoliant.yml 并且您需要其中一个图表以 svg 呈现，请覆盖format标记中的选项：

SVG diagram:

<bpmn format="svg">
...
</bpmn>

标签还有一个专属选项caption——图表图像的降价标题。

Diagram with a caption:

<bpmn caption="Diagram of the supply process">
...
</bpmn>