Diagrams¶

The mermaid, plantuml, and uml directives render as live diagrams in the Rendered preview. Diagrams are drawn client-side by Mermaid; plantuml and uml sources are translated to Mermaid on the fly. All three work in both reStructuredText and Markdown (MyST).

This reference describes the Rendered preview mode; in Structural mode every directive and role renders as a uniform placeholder (see Authoring).

Mermaid¶

A mermaid directive takes its diagram either as inline content or as a file argument — one or the other. If you supply both at once, that is reported as a diagnostic and the inline content is used.

Inline content:

.. mermaid::
   :caption: Firmware boot sequence
   :align: center

   sequenceDiagram
       Bootloader->>Firmware: verify signature
       Firmware-->>Bootloader: ok

A file argument instead:

.. mermaid:: diagrams/boot-sequence.mmd
   :align: center

See the Mermaid documentation for the diagram syntax itself.

PlantUML and UML¶

The plantuml and uml directives accept PlantUML source, which is translated to Mermaid before rendering.

This translation is best-effort and covers a subset of PlantUML — sequence, class, component, state, and activity diagrams. Other PlantUML diagram families, and individual lines the translator does not recognise, fall back to showing the source as a placeholder rather than a broken diagram. The surrounding @startuml / @enduml markers are optional.

Preprocessing¶

PlantUML preprocessing is applied to the directive body before it is translated, so a diagram can be generated rather than written out in full: variables (!$name = …), !define / !definelong, !function and !procedure, conditionals (!if / !ifdef / !else), loops (!while / !foreach) and the string, list and arithmetic % builtins (%strlen, %substr, %splitstr, %size, %upper, %lower, %intval, %dec2hex and the rest) all work. This needs no configuration and cannot be turned off.

The C4 standard library is bundled, so !include <C4/C4_Container.puml> (and the other C4_* files) resolves offline and the Person() / Container() / Rel() macros expand.

Not yet supported:

Including your own files, or a URL — !include, !include_once, !include_many and !includeurl resolve only against the bundled standard library. Local files are not read and URLs are never fetched; local-file includes are planned.
Themes — !theme is understood but no themes are bundled yet, so it is skipped.
Sub-part includes — !startsub / !endsub / !includesub, !includedef and !import are recognised but not executed.
Structured data — a variable holding a JSON object or array cannot be navigated ($obj.field, $arr[0]), and %load_json is not implemented. Lists produced by %splitstr do work with !foreach and %size.
Builtins that read the clock, the environment or the file being built — %date, %now, %random, %getenv, %filename, %filename_no_extension, %dirpath, %filedate and %file_exists are recognised but return an empty string. A diagram whose content depended on any of them would not be reproducible from its own source, and %getenv would additionally read the build environment.

Anything on that list is skipped, not fatal: the rest of the diagram still renders, exactly as it would have before the directive was written.

If a body preprocesses away to nothing — every line inside an !if that turned out false, say — the directive falls back to showing its source. PlantUML itself would draw an empty diagram there; showing the source is the more useful of the two.

Options¶

The following options are applied to the rendered diagram:

Option	Effect
`:caption:`	Wraps the diagram as a figure with the caption below it. The caption text is shown as written — inline markup is not interpreted.
`:align:`	Aligns the diagram: `left`, `center`, or `right`.
`:name:`	Gives the diagram a stable cross-reference target you can `:ref:`. In a built site the name becomes an `id` on the diagram (normalised the usual way — `My Flow` becomes `my-flow`), and a `¶` permalink appears in the caption when the diagram has a `:caption:`. An unnamed diagram gets neither, and never a generated positional id. See Differences from a Sphinx build for the family-wide rule.
`:width:` / `:height:`	Sizes the diagram container, in the preview and in `ubc build html` alike (a bare number is treated as pixels). Any CSS unit is accepted, because the container is a CSS-sized box; a value that is not a size raises a warning and the diagram renders without that dimension. The same two options are available on `needflow` and `needsequence`. This is a noted divergence — see Differences from a Sphinx build.
`:alt:`, `:scale:` / `:max-width:`, `:config:`, `:title:`, `:zoom:`	Accepted so they do not raise errors, but not yet applied to the rendered diagram.

Behaviour notes¶

Diagrams follow the editor theme, and re-render when you switch between light and dark.
A diagram whose source has a syntax error keeps its source visible with an error style, so you can see and fix it, rather than showing a blank space.

Note

Diagrams are designed to degrade gracefully. Whether the input is an unrecognised PlantUML family, a line the translator cannot handle, or Mermaid source with a syntax error, the preview shows the source (as a placeholder or with an error style) instead of a blank or broken block — so you always have something to read and correct.