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.

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`.
`:width:` / `:height:`	Sizes the diagram container (a bare number is treated as pixels). 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.