BPMN Conversion

Overview

The convert command transforms BPMN 2.0 XML files into diagrams-compliant YAML specs. This lets you take existing business process models from tools like Camunda, Bizagi, or any BPMN-compliant modeler and render them as clean, themed diagrams.

diagrams convert process.bpmn -o output.yaml

Basic Usage

Convert a BPMN file to YAML:

diagrams convert process.bpmn -o process.yaml

Convert and render in one step:

diagrams convert process.bpmn -r -f png -o process.png

Convert and render directly to PowerPoint:

diagrams convert process.bpmn -r -f pptx -o process.pptx

CLI Options

Flag	Description	Default
-o, --output	Output file path	diagram.yaml
-d, --direction	Layout direction (TB, LR, BT, RL)	TB
-r, --render	Render the output immediately after conversion	false
-f, --format	Output format when rendering (svg, png, pdf, pptx)	svg
-t, --theme	Theme to apply when rendering	default

Supported BPMN Elements

The converter maps standard BPMN elements to diagram nodes with appropriate shapes, styles, and Geist icon defaults.

Tasks

BPMN Element	Shape	Default Icon
Task	rectangle	geist:clipboard
User Task	rectangle	geist:user
Service Task	rectangle	geist:settings
Script Task	rectangle	geist:terminal
Send Task	rectangle	geist:send
Receive Task	rectangle	geist:inbox
Manual Task	rectangle	geist:hand
Business Rule Task	rectangle	geist:scale

Events

BPMN Element	Shape	Default Icon
Start Event	circle	geist:play
End Event	circle	geist:stop-circle
Intermediate Catch Event	circle	geist:pause
Intermediate Throw Event	circle	geist:arrow-up-right
Timer Event	circle	geist:clock
Message Event	circle	geist:mail
Signal Event	circle	geist:radio

Gateways

BPMN Element	Shape	Default Icon
Exclusive Gateway	diamond	geist:git-branch
Parallel Gateway	diamond	geist:layers
Inclusive Gateway	diamond	geist:circle-ellipsis
Event-Based Gateway	diamond	geist:zap

Structural Elements

BPMN Element	Mapping
Lane / Pool	Mapped to diagram groups
Sub-Process	Mapped to diagram groups
Sequence Flow	Mapped to solid edges
Message Flow	Mapped to dashed edges

Example

Given a BPMN file describing an order process:

# Convert to YAML
diagrams convert order-process.bpmn -o order.yaml

# Convert and render with a theme
diagrams convert order-process.bpmn -r -f png -t nord -o order.png

The converter will produce a YAML spec with nodes for each BPMN task, event, and gateway, edges for sequence and message flows, and groups for lanes and pools -- all with appropriate Geist icon defaults.

Customizing Output

After converting to YAML, you can edit the generated spec to:

• Change icons to better fit your use case
• Adjust node labels and colors
• Add or remove edges
• Apply different themes

# Convert to YAML first
diagrams convert process.bpmn -o process.yaml

# Edit process.yaml as needed, then render
diagrams render process.yaml -o process.svg --theme cyberpunk