[build.plantuml]

External PlantUML renderer settings shared by every builder.

Each builder also has a plantuml table of its own, such as [build.html.plantuml], so the executable can be named once here for the whole project. A builder’s own table inherits every key it does not set from [build.plantuml] and wins on every key it does, enabled = false included.

ubCode can draw the needuml and needarch views, the authored uml / plantuml directives (and their MyST {uml} / {plantuml} fences), and — when needflow / needsequence are set — the needflow and needsequence views, by running a PlantUML executable you install and maintain, instead of converting them to Mermaid. It is off by default, and the live preview always uses the Mermaid conversion.

These keys can be written once in [build.plantuml] for every output format, or in one format’s own table such as [build.html.plantuml], which inherits every key it does not set from [build.plantuml] and wins on every key it does, enabled = false included.

PlantUML 1.2026.2 or newer is required. Older releases accept the command-line options this feature relies on and then ignore them, so the diagram it produced would not be under the controls described here.

ubCode always sets PlantUML’s SANDBOX profile, as a JVM property and in the environment. That is a safe default rather than a guarantee: the executable is yours, and what you put in command can relax it — a later -DPLANTUML_SECURITY_PROFILE=UNSECURE, a wrapper script that re-exports the profile, or an entry that strips the environment. That is your explicit choice: ubCode does not diagnose which of the two PlantUML prefers, and cannot contain what PlantUML then reads.

Guide: Sharing the renderer between builders.

build.plantuml.command

Type:

array of strings

Default:

[]

The PlantUML executable to run, written as a command and its arguments.

Always a list, never a single string. For a JAR give the launcher and the JAR — ["java", "-jar", "/opt/plantuml.jar"] — and put any JVM options (-Xmx512m) before -jar; for a wrapper script or a native build, one entry is enough.

The FIRST entry is the program: a bare name is looked up on PATH, and one containing a path separator is taken relative to this ubproject.toml. Every entry after it is passed through EXACTLY as written.

To point at a file beside this ubproject.toml, write {config_dir} and ubCode replaces it with that directory — anywhere in any entry, as often as you like: ["java", "-jar", "{config_dir}/libs/plantuml.jar"]. Nothing else in an argument is rewritten, so a container image name, a KEY=VALUE pair or a URL reaches your program unchanged.

Required when the renderer is enabled — a command that cannot be run is reported as the build warning build.plantuml_exec_failed, and so is an unset or empty one.

ubCode always runs PlantUML under its SANDBOX profile, and what you write here can relax it: a later -DPLANTUML_SECURITY_PROFILE=UNSECURE argument, or a wrapper script that re-exports the profile before starting PlantUML. That is your explicit choice — ubCode does not diagnose whether PlantUML prefers the property or the environment, cannot contain what PlantUML then reads, and PlantUML’s own allowlist confines neither .. nor symbolic links.

build.plantuml.enabled

Type:

boolean

Default:

false

Render PlantUML diagrams with an external PlantUML executable instead of converting them to Mermaid.

Applies to the needuml / needarch views and the authored uml / plantuml directives in the built output, and to the needflow / needsequence views when their own keys are also set. Defaults to false, which leaves each builder to draw the diagram itself — in the HTML site, as the Mermaid conversion. The live preview always uses the Mermaid conversion, so an enabled project’s diagrams can look different in the preview than on the built page. Writing this table without setting this key leaves the renderer off.

build.plantuml.min_version

Type:

string

Default:

""

The oldest PlantUML version this project accepts.

Written the way PlantUML writes it, 1.2026.4, and checked once per build against the version the executable reports. Below it the renderer is switched off for that build with the warning build.plantuml_version_unsupported and the diagrams fall back to what the builder draws without the renderer (in the HTML site, the Mermaid conversion).

This can only RAISE the bar: it cannot be set below the built-in minimum of 1.2026.2, and a lower value is reported as the build warning build.plantuml_exec_failed and ignored in favour of that minimum. An executable whose reported version cannot be read at all is reported as build.plantuml_version_unparsed and not used, since there is then no version to check against the minimum.

Diagram appearance can change between PlantUML releases, so upgrading can change how your diagrams look. Unset or "" means 1.2026.2.

build.plantuml.needflow

Type:

boolean

Default:

false

Also draw the needflow views with the external PlantUML executable.

Needs enabled as well: this key chooses which diagrams the renderer draws, never whether there is one, so needflow = true on its own changes nothing. Defaults to false in both builders, which draws every needflow the way ubCode draws it today (in the HTML site, as a client-side Mermaid flowchart; in the PDF, as a box showing the diagram source).

This is a FIDELITY setting: the diagram is laid out by PlantUML itself, the way a Sphinx-Needs build with needs_flow_engine = "plantuml" lays it out, and each node becomes a link to its need. Some intents cannot be carried over exactly — :direction: up and :direction: left are drawn on their axis mate, a type style that is not a PlantUML keyword is drawn as a rectangle, and style_start / style_end are ignored.

[needs] flow_engine is the low-precedence default for this key, so a ubproject.toml shared with a Sphinx-Needs build need not say the same thing twice. A diagram’s own :engine: option overrides both, in either direction. The live preview always uses the Mermaid conversion, whatever this says.

build.plantuml.needsequence

Type:

boolean

Default:

false

Also draw the needsequence views with the external PlantUML executable.

Needs enabled as well, exactly as needflow does, and defaults to false in both builders. A separate key from needflow because a project may well want its traceability graph drawn by PlantUML and its message diagrams left as they are.

[needs] flow_engine does NOT drive this key. Sphinx-Needs’ own needsequence is PlantUML-only and has no engine option at all, so the key that chooses between engines has nothing to say about this family.

With it off, a needsequence is the Mermaid sequence diagram ubCode draws itself (a box showing that source, in the PDF). With it on, it is laid out by PlantUML. The live preview always uses the Mermaid conversion, whatever this says.

build.plantuml.timeout

Type:

integer

Default:

60

How long the whole diagram-rendering step may take, in seconds.

The bound covers the single run that renders every diagram needing an update, not each diagram. Diagrams that produced no output when it expires are reported as the build warning build.plantuml_timeout and fall back to what the builder draws without the renderer (in the HTML site, the Mermaid conversion). Defaults to 60; 0 is refused as build.plantuml_exec_failed.