Skip to content

PlantUML

Render sequence, class, component, activity and use-case diagrams in the browser with bundled assets and no rendering service.

Write PlantUML source in a plantuml fence. OINK renders it in the reader’s browser with two bundled scripts. No Java, Graphviz executable, npm install, CDN or rendering service is needed. Diagram source stays in the browser when using local rendering.

Local rendering in OINK 1.4.0

Local rendering is available when PlantUML is enabled without an endpoint. An explicit rendering endpoint continues to select server mode.

Enable it in your site configuration:

hugo.yml
params:
  plantuml: true

plantuml: { enable: true } also works. The default remains disabled. Enabled pages without PlantUML fences do not load either engine script.

Sequence diagram

Wrap the source in a plantuml fence. This live example renders entirely locally:

```plantuml
@startuml
actor Reader
participant Browser
Reader -> Browser : open the page
Browser -> Browser : render locally
Browser --> Reader : SVG diagram
@enduml
```
@startuml
actor Reader
participant Browser
Reader -> Browser : open the page
Browser -> Browser : render locally
Browser --> Reader : SVG diagram
@enduml

Class diagram

Declare classes, fields and relationship cardinalities.

@startuml
class Publication {
  + pubname : name
  + puballtables : bool
  + pubinsert / pubupdate / pubdelete : bool
}
class Subscription {
  + subname : name
  + subconninfo : text
  + subslotname : name
}
class ReplicationSlot {
  + slot_name : name
  + plugin : name
  + confirmed_flush_lsn : pg_lsn
}
Publication "1" -- "0..*" Subscription : subscribed by
Subscription "1" -- "1" ReplicationSlot : bound to
@enduml

Component diagram

Packages group components; arrows show their dependencies.

@startuml
package "Monitoring node" {
  [Grafana] as grafana
  [Prometheus] as prom
  [Alertmanager] as alert
}
package "Database node" {
  [node_exporter] as node
  [pg_exporter] as pgexp
  [PostgreSQL] as pg
}
pg --> pgexp : query the statistics views
node --> prom : /metrics
pgexp --> prom : /metrics
prom --> alert : rule fired
grafana --> prom : PromQL
@enduml

Activity diagram

Use decisions and branches to explain a workflow.

@startuml
start
:write content/docs/**/*.md;
:add the translated peer, copying the rendered heading IDs;
if (hugo passes?) then (yes)
  :npm test;
else (no)
  :fix using the file and line in the error;
  stop
endif
if (tests green?) then (yes)
  :open the PR;
  stop
else (no)
  :back to editing;
  stop
endif
@enduml

Use-case diagram

Actors and use cases describe what each reader can do.

@startuml
left to right direction
actor Reader as reader
actor Author as author
actor Maintainer as maintainer
rectangle "Documentation site" {
  reader --> (full-text search)
  reader --> (switch language)
  reader --> (export the print view)
  author --> (add a page)
  author --> (preview locally)
  maintainer --> (upgrade the theme)
  maintainer --> (publish)
}
@enduml

Dark mode

Local diagrams follow light/dark mode; authored skinparam settings still apply. Obsolete render results are discarded when the mode changes. An open viewer retains its zoom and pan position.

Enlarge, source and download

Local PlantUML uses the same viewer as Mermaid. Use the corner button to open it, drag or arrow keys to pan, wheel/pinch/+/- to zoom, Fit to window or 0 to fit, and Esc to close and restore focus. The viewer reuses the Blob image without inserting PlantUML SVG markup or links into the page DOM, and without rendering again.

Source and Copy code preserve arrows, quotes, ampersands and Chinese. Download SVG exports a styled standalone file; external resource dependencies prevent export. Failures show feedback in the toolbar. The source disclosure below each diagram also supports viewing and copying. Explicit server mode keeps its legacy behavior.

Demand loading and printing

The two local engines load once when a diagram comes within 320px of the viewport. Hidden tabs, disclosures and zero-width containers wait until shown. Browsers without IntersectionObserver use scroll and size checks. Mermaid and PlantUML render serially on the main thread. No installation or build step is added.

Ordinary browser printing retains rendered images and shows source for unrendered diagrams. It cannot wait for asynchronous engines; visit and expand the diagrams first when you need pictures throughout. Dedicated Print, Markdown and RSS keep source fallback.

Optional rendering service

Existing sites can keep an explicitly configured endpoint:

hugo.yml
params:
  plantuml:
    enable: true
    svg_image_url: https://plantuml.internal.example/plantuml/svg/
    svg: false

A nonempty svg_image_url selects server rendering. Removing it selects local rendering. The server URL must end with the appropriate path separator and be an HTTP(S) URL with a host or a same-site path. Invalid endpoints warn and disable rendering; they do not silently switch modes. OINK supplies no public endpoint.

Server mode sends encoded diagram source to that endpoint and retains its existing svg option. Local mode ignores svg: generated SVG is displayed as an image, so authored links and markup do not enter the page DOM.

Outputs

Output Result
HTML Local SVG image when enabled; readable source until rendering succeeds
Browser print of HTML Rendered image scaled to fit, or readable source if not rendered
Dedicated Print output Readable source, with no PlantUML runtime
Markdown and RSS Original diagram source; no rendering request

With JavaScript disabled, a failed engine download, unsupported input or a rendering error, the source remains readable. A failed diagram does not prevent other diagrams on the page from rendering.

Parameters

params.plantuml , boolean or map , defaultdisabled
true enables local rendering
params.plantuml.enable , boolean , defaultfalse
Enables the map form
params.plantuml.svg_image_url , string , defaultabsent
Optional endpoint selecting legacy server rendering
params.plantuml.svg , boolean , defaultfalse
Server mode only: inline SVG instead of an image

Fences do not accept code-block title, copy, line-number, numbering or zoom attributes. Source without @startuml / @enduml is wrapped for local rendering; explicit diagram delimiters are preserved.

Limits

  • The browser bundle includes the core engine and Graphviz layout only. !include, !includeurl, external themes, C4, AWS and other optional sprite libraries are not downloaded. Unsupported resources leave the source visible. Use self-contained diagrams, pre-rendered images, or an explicit server for these.
  • The pinned engine is @plantuml/core 1.2026.9 with Viz.js 3.24.0. The two scripts total about 4.8 MB before compression, or 1.7 MB with gzip. They load only as enabled diagrams approach the viewport; normal HTTP caching applies.
  • Rendering uses the browser’s JavaScript and WebAssembly support. Sites with a restrictive CSP need to allow their own scripts, WebAssembly compilation (wasm-unsafe-eval) and blob: images. Blocked resources retain source.
  • Large diagrams still cost browser CPU and memory. Rendering proceeds one diagram at a time; this is not a background-worker renderer. After an uncancellable engine timeout, remaining PlantUML figures keep source until the page is reloaded.
  • Diagrams are images: SVG hyperlinks are inactive. Numbering is not part of this integration.
  • Mermaid — another bundled browser diagram engine
  • Images — pre-rendered diagrams, numbering and zoom
  • Configuration — site settings