PlantUML
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 is available when PlantUML is enabled without an endpoint. An explicit rendering endpoint continues to select server mode.
Enable it in your site configuration:
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:
@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:
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
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/core1.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) andblob: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.
Related
- Mermaid — another bundled browser diagram engine
- Images — pre-rendered diagrams, numbering and zoom
- Configuration — site settings