Render PlantUML and Graphviz/DOT diagrams in Docusaurus 3 entirely in the browser — no Java, no PlantUML server, no Graphviz install, no Kroki, no CDN.
→ Live demo — every diagram on that site is rendered by your own browser.
The package name says PlantUML, and it renders Graphviz too. Graphviz support was added in 1.1.0; the name is kept for the sake of everyone who already depends on it. See Graphviz diagrams.
Write a plantuml fence in any .md or .mdx file and the code block is replaced, in the
reader's browser, with an SVG rendered by the official @plantuml/core
package:
```plantuml title="Authentication sequence"
@startuml
actor User
participant Browser
participant API
User -> Browser: Sign in
Browser -> API: POST /sessions
API --> Browser: Access token
Browser --> User: Signed in
@enduml
```…and a dot fence is replaced with an SVG laid out by Graphviz:
```dot title="Build pipeline"
digraph {
rankdir=LR;
src -> build -> test -> deploy;
}
```Rendering is 100% same-origin and client-side. Your diagram source never leaves the
browser. It is not sent to plantuml.com, to a Kroki instance, or to any other service, and
the engines themselves are served from your own site's baseUrl.
Status: stable. 1.0.0 fixes the public surface — plugin options, fence metadata flags,
the data-* attributes, and the shape of the rendered markup. Breaking changes to any of them
require a major version.
Explicitly not covered by that promise: the generated CSS-module class names, the exact SVG
@plantuml/core produces, and the renderer, queue and cache internals — which is why none of
them are exported.
| Requirement | Supported |
|---|---|
| Docusaurus | 3.5.0 and later 3.x |
| Node.js (build) | >= 20.9.0 (the Node 20 LTS line) |
| React | 18.x or 19.x (matching your Docusaurus install) |
| Bundler | webpack (default) and Rspack (future.v4 / @docusaurus/faster) |
| PlantUML engine | @plantuml/core >= 1.2026.8 |
| Browsers | Modern evergreen browsers; no IE (see Browser compatibility) |
The plugin requires a theme that already provides MDXComponents/Code — in practice
@docusaurus/theme-classic, which you almost certainly have through preset-classic.
CI runs the full browser suite against Docusaurus 3.5.2 (the oldest supported release), the
version the example pins, and the newest 3.x resolved at run time.
This is an upstream issue that has nothing to do with this plugin, but it will stop your build before the plugin is ever reached, so it is worth knowing about.
@docusaurus/bundler depended on webpackbar@^6.0.1 up to and including Docusaurus 3.10.0,
and webpackbar 6 fails ProgressPlugin's option validation against webpack >= 5.109. A
fresh install of any Docusaurus 3.5–3.10.0 site therefore fails to build with:
ValidationError: Invalid options object.
Progress Plugin has been initialized using an options object that does not match the API schema.
If you are on one of those versions and see this, add an override to your site's
package.json and reinstall:
{
"overrides": {
"webpackbar": "^7.0.0"
}
}Docusaurus 3.10.2 and later depend on webpackbar@^7 already and need no override. This is
exactly what the compatibility job in CI does to test the 3.5.2 leg.
@plantuml/core is MIT-licensed from version 1.2026.6 onwards. Earlier versions were
published under GPL-3.0-or-later. This plugin depends on ^1.2026.8 — which is well past that
line, and is also the release that added the maxSvgSize option
maxSvgSize relies on. Pinning or deduping @plantuml/core below 1.2026.8
fails the build with a message naming the version, rather than silently ignoring the option.
npm install @matfsw/docusaurus-plantuml-plugin@plantuml/core, copy-webpack-plugin and dompurify are ordinary dependencies of this
package and are installed for you. @docusaurus/core, react and react-dom are peer
dependencies and come from your site.
// docusaurus.config.ts
import type {Config} from '@docusaurus/types';
const config: Config = {
// ...
plugins: ['@matfsw/docusaurus-plantuml-plugin'],
};
export default config;That is the whole setup. Every option has a default; pass an options object only to change one:
// docusaurus.config.ts
import type {Config} from '@docusaurus/types';
import type {PlantUmlPluginOptions} from '@matfsw/docusaurus-plantuml-plugin';
const config: Config = {
// ...
plugins: [
[
'@matfsw/docusaurus-plantuml-plugin',
{
languages: ['plantuml', 'puml'],
theme: 'auto',
lazy: true,
cache: 'memory',
sanitizeSvg: true,
showSourceOnError: true,
renderTimeoutMs: 20_000,
cacheMaxEntries: 50,
maxSvgSize: 32_768,
zoom: true,
graphviz: {
enabled: true,
languages: ['dot', 'graphviz', 'gv'],
engine: 'dot',
allowEngineOverride: true,
maxSourceBytes: 100_000,
transparentBackground: true,
},
} satisfies PlantUmlPluginOptions,
],
],
};
export default config;A plain JavaScript docusaurus.config.js works too — the package ships both an ESM and a
CommonJS build of the Node-side entry point.
# Sequence diagram
```plantuml title="Authentication sequence"
@startuml
actor User
participant API
User -> API: POST /sessions
API --> User: Access token
@enduml
```The title="..." in the fence metastring becomes both the <figcaption> and the accessible
label of the diagram. It is optional.
The same fence syntax works in MDX, alongside JSX:
import Admonition from '@theme/Admonition';
<Admonition type="info" title="MDX">
Fenced PlantUML works here too.
</Admonition>
```puml
@startuml
Alice -> Bob : puml alias in MDX
@enduml
```By default the plugin claims five fence languages across two engines:
| Engine | Default languages | Option |
|---|---|---|
| PlantUML | plantuml, puml |
languages |
| Graphviz | dot, graphviz, gv |
graphviz.languages |
Matching is case-insensitive, so ```PlantUML, ```PUML, ```DOT and ```dot
are all recognised. Change either set with its option; entries are normalised to lower case,
must be non-empty, must not repeat, and the two sets must not overlap.
Upgrading from 1.0.x:
dot,graphvizandgvfences were previously rendered as ordinary code blocks and are now rendered as diagrams. If you have such fences that are meant to stay code, setgraphviz: {enabled: false}, or narrowgraphviz.languages.
Everything else — inline code, ordinary fenced blocks in any other language, and code blocks
authored as JSX children — is delegated to the original Docusaurus Code component with its
props untouched. Existing code-block behaviour (highlighting, line numbers, titles,
showLineNumbers, copy button) is unchanged.
| Option | Type | Default | Description |
|---|---|---|---|
languages |
string[] |
['plantuml', 'puml'] |
Fence languages treated as PlantUML. Matched case-insensitively; must contain at least one non-empty, non-duplicate entry. |
theme |
'auto' | 'light' | 'dark' |
'auto' |
Diagram colour scheme. auto follows the Docusaurus colour mode; light/dark pin it. |
lazy |
boolean |
true |
Render a diagram only once it scrolls near the viewport (300 px root margin). |
cache |
'none' | 'memory' | 'session' |
'memory' |
Where rendered SVG is cached. |
sanitizeSvg |
boolean |
true |
Run rendered SVG through DOMPurify before inserting it. See Security model. |
showSourceOnError |
boolean |
true |
Include the diagram source in a <details> block on the error panel. |
renderTimeoutMs |
number |
20000 |
Abort a single render (and the runtime load) after this many milliseconds. Integer, 100–600000. |
cacheMaxEntries |
number |
50 |
Upper bound on cached SVG entries. Positive integer. |
maxSvgSize |
number |
32768 |
Refuse a PlantUML diagram wider or taller than this many points. Non-negative integer; 0 disables the check. See Diagram size. |
zoom |
boolean |
true |
Let readers zoom and pan diagrams. Adds a control toolbar and a focusable viewport. Override per fence with zoom=false. |
showSource |
boolean |
true |
Offer a toolbar control that reveals the diagram source and copies it to the clipboard. Override per fence with showSource=false. |
graphviz |
object |
see below | Graphviz/DOT support. See Graphviz options. |
stdlib |
object | false |
see below | PlantUML standard library (!include <C4/…>). See Standard library options. |
id |
string |
'default' |
Docusaurus plugin instance id; only relevant if you register the plugin more than once. |
Every option above except graphviz, stdlib, theme and maxSvgSize applies to both
engines: lazy, cache, sanitizeSvg, showSourceOnError, renderTimeoutMs,
cacheMaxEntries and zoom behave identically for a dot fence and a plantuml fence.
theme is the exception for colour — see Light and dark mode — and
maxSvgSize is PlantUML-only, because Graphviz fences are bounded by
graphviz.maxSourceBytes instead.
Options are validated during the Docusaurus configuration phase, before anything is built.
Unknown keys are rejected rather than ignored, because a typo in docusaurus.config.ts
would otherwise silently disable the option you meant to set:
[docusaurus-plugin-plantuml-client] Unknown option 'sanitiseSvg'. Supported options:
'languages', 'theme', 'lazy', 'cache', 'sanitizeSvg', 'showSourceOnError',
'renderTimeoutMs', 'cacheMaxEntries', 'maxSvgSize', 'zoom', 'showSource', 'graphviz',
'stdlib'.
The same is true one level deeper, so graphviz: {enigne: 'neato'} fails the build rather than
quietly doing nothing.
PlantUmlPluginOptions, ResolvedPlantUmlOptions, GraphvizOptions,
ResolvedGraphvizOptions, GraphvizEngine, GRAPHVIZ_ENGINES, StdlibOptions,
ResolvedStdlibOptions, CacheMode, DiagramTheme, DEFAULT_OPTIONS,
DEFAULT_GRAPHVIZ_OPTIONS, resolveOptions and PlantUmlOptionsError are exported from the
package root. The renderer, queue and cache internals are deliberately not
exported.
dot, graphviz and gv fences are laid out by Graphviz compiled to WebAssembly,
in the reader's browser, exactly like PlantUML fences:
```dot title="Build pipeline"
digraph {
rankdir=LR;
node [shape=box, style=rounded];
src -> build -> test -> deploy;
}
```This is the part worth knowing: the plugin already shipped Graphviz before it could render
DOT. @plantuml/core bundles viz-global.js — Viz.js containing Graphviz — because PlantUML
needs it for its own layout, and the plugin has been emitting and loading it since 0.1.0.
Rendering DOT reuses that engine, so a site that already renders PlantUML pays zero
additional bytes for Graphviz support. See
ADR 0004.
The reverse also holds: a page containing only DOT diagrams loads only viz-global.js
(~1.4 MB) and never fetches the ~6.8 MB PlantUML engine.
Graphviz ships eleven layout engines. The default is dot; any fence can pick another with
engine=:
```dot title="Undirected mesh" engine=neato
graph { a -- b -- c -- a }
```Available engines: circo, dot, fdp, neato, nop, nop1, nop2, osage,
patchwork, sfdp, twopi. An unknown name fails with the supported set spelled out. Set
graphviz.allowEngineOverride: false to ignore the fence flag and pin every diagram to the
configured engine.
Graphviz has no dark theme — it draws black on white regardless of the page. Rather than re-rendering the graph for each colour mode, the plugin retargets Graphviz's defaults at the page's text colour in CSS, and renders on a transparent background.
Colours set in the DOT source always win. The rules only match elements Graphviz coloured
with its own black default (stroke="black", fill="black", and <text> with no fill), so
color=red, fillcolor=lightblue and friends are emitted and displayed exactly as authored,
in both modes.
Because nothing is re-rendered, toggling the theme on a page of DOT diagrams costs no layout work at all and does not disturb a reader's zoom.
Graphviz returns structured diagnostics, so an invalid diagram is reported with the engine's own message including the offending line:
Error: Graphviz diagram could not be rendered
syntax error in line 3 near '}'
graphviz: {
enabled: true, // intercept DOT fences at all
languages: ['dot', 'graphviz', 'gv'], // fence languages, matched case-insensitively
engine: 'dot', // default layout engine
allowEngineOverride: true, // permit `engine=neato` on a fence
maxSourceBytes: 100_000, // refuse larger sources; see below
transparentBackground: true, // omit Graphviz's opaque white background
}| Option | Type | Default | Description |
|---|---|---|---|
enabled |
boolean |
true |
Intercept DOT fences. false leaves them as ordinary, highlighted code blocks. |
languages |
string[] |
['dot', 'graphviz', 'gv'] |
Fence languages treated as Graphviz. Must not overlap the top-level languages. |
engine |
string |
'dot' |
Default layout engine, one of the eleven listed above. |
allowEngineOverride |
boolean |
true |
Whether a fence may select its own engine with engine=. |
maxSourceBytes |
number |
100000 |
Refuse sources larger than this many UTF-8 bytes, showing an explanatory panel instead. |
transparentBackground |
boolean |
true |
Render with bgcolor=transparent so the page background shows through. |
A language claimed by both engines fails the build, because a fence has exactly one language and the result would otherwise depend on evaluation order:
[docusaurus-plugin-plantuml-client] options.graphviz.languages and options.languages both
claim 'dot'. A fence language can only belong to one engine.
Graphviz lays out synchronously, so an enormous graph blocks the main thread rather than merely taking a while. Measured on the bundled engine: a 300-edge graph renders in ~26 ms (imperceptible), while a 3 000-edge graph takes ~2.25 s — a visible freeze. The default limit turns that freeze into a contained error panel. Raise it if you genuinely have diagrams that large, and expect the page to stall while they render.
The check happens before the engine is downloaded, so refusing an oversized diagram is free.
!include <C4/C4_Container> works out of the box. Nothing to install, nothing to configure:
```plantuml title="C4 container diagram"
@startuml
!include <C4/C4_Container>
Person(user, "Reader", "Reads the documentation")
Container(browser, "Browser", "JavaScript", "Renders diagrams locally")
Rel(user, browser, "Opens a page")
@enduml
```Both spellings of the include resolve — <C4/C4_Container> and <C4/C4_Container.puml> —
and so do the includes the library makes of itself: C4_Container pulls in C4_Context,
k8s/Common pulls in <c4/…>, and none of that has to be written in the fence.
Namespaces are fetched per page, on demand. A page with a C4 diagram downloads 29 KB
gzipped; a page with no standard library include downloads nothing at all. The bundles are
served from your own baseUrl like every other asset — no CDN, no plantuml.com.
| Namespace | Library | Transfer | Licence |
|---|---|---|---|
c4 |
C4-PlantUML | 29 KB | MIT |
archimate |
Archimate-PlantUML | 34 KB | MIT |
eip |
EIP-PlantUML | 21 KB | MIT |
k8s |
kubernetes-PlantUML | 23 KB | MIT |
kubernetes |
kubernetes sprites | 221 KB | Apache-2.0 |
azure |
Azure-PlantUML | 160 KB | MIT |
office |
plantuml-office | 160 KB | MIT |
cloudinsight |
cicon sprites | 24 KB | MIT |
domainstory |
DomainStory-PlantUML | 5 KB | MIT |
Transfer figures are gzipped, per namespace, once per browsing session.
assets/stdlib/LICENSES.md records the exact upstream version and
licence of each. The bundles are generated from a pinned
plantuml-stdlib commit by
npm run stdlib:update.
The standard library in full is 265 MB of source (28 MB gzipped), most of it icon sets:
aws alone is 114 MB, and ibm, tupadr3, material7.4.47 and awslib14/awslib20 account
for most of the rest. Shipping that in an npm package is not reasonable, and several other
namespaces — classy, classy-c4, cloudogu, edgy, elastic, gcp, osa2 — declare no
licence at all upstream, which makes redistributing them your call rather than this package's.
domainstory is left out for a third reason: it is small and MIT licensed, but every element it
draws resolves an icon out of material2.1.19, so it cannot render without 6.8 MB of icons
beside it — use it with include: ['domainstory', 'material2.1.19'].
Any of them can be added from your own checkout:
git clone --depth 1 https://github.com/plantuml/plantuml-stdlib vendor/plantuml-stdlib{
stdlib: {
include: ['aws', 'tupadr3'],
source: 'vendor/plantuml-stdlib/stdlib',
},
}Bundles for those namespaces are generated during the build and cached under .docusaurus, so
only the first build pays for it. Naming a namespace that is vendored replaces it with the
copy from your checkout, which is also how you pin a newer C4 than the one shipped here.
| Option | Type | Default | Description |
|---|---|---|---|
enabled |
boolean |
true |
Resolve !include <namespace/…> at all. stdlib: false is shorthand for {enabled: false}. |
include |
string[] |
[] |
Extra namespaces to make available. Each must be found in source, or the build fails naming it. |
source |
string | string[] |
[] |
stdlib directories of plantuml-stdlib checkouts, relative to the site directory or absolute. Required whenever include is set. |
namespaces |
string[] |
all | Narrow the vendored namespaces emitted into the build. Dependencies of the named ones are kept regardless. |
Namespaces are matched case-insensitively, because the engine lower-cases <C4/…> before it
looks anything up.
A diagram that includes a namespace the site does not provide gets the plugin's error panel, naming what is missing and how to add it — not PlantUML's grey "Fatal parsing error" picture:
This diagram includes <aws/…>, but the 'aws' standard library namespace is not available on
this site. Add it to the plugin's `stdlib.include` option and point `stdlib.source` at a
plantuml-stdlib checkout that contains it.
{
stdlib: false;
}Nothing is emitted into the build, and a diagram with a standard library include says so instead of failing inside the engine. See ADR 0005 for why the bundles are loaded the way they are.
The two engines handle this differently, because PlantUML has a real dark theme and Graphviz does not.
With theme: 'auto' (the default), the diagram follows the site's colour mode through
Docusaurus' own useColorMode() hook. Toggling the site theme re-renders every visible
diagram with the engine's {dark} flag flipped, which changes PlantUML's own fill and stroke
palette rather than merely inverting the picture with CSS.
The colour mode is part of the cache key, so a toggle can never serve the other mode's SVG, and the engine itself is loaded once per page regardless of how often you toggle.
Set theme: 'light' or theme: 'dark' to pin the diagram palette independently of the site
theme.
Graphviz draws black on white and has no dark palette to ask for, so the plugin adapts its
defaults with CSS instead of rendering the graph twice. A colour-mode toggle therefore costs
no layout work for DOT diagrams, does not reset the reader's zoom, and needs no second cache
entry. The theme option does not apply to them.
See Colours and dark mode for exactly which elements are adapted and why authored colours are never touched.
The current mode is exposed on the wrapper as data-plantuml-theme="light|dark" for every
diagram, whichever engine produced it.
Large diagrams are unreadable at column width. Rendered diagrams are therefore zoomable and pannable by default, with a small control toolbar above the picture.
A zoomable diagram is two stacked rows: the controls, at the top right, and the diagram beneath them. The search bar opens beside the toolbar, in the same row, and the toolbar wraps rather than overflowing a narrow column.
Nothing is painted over the picture, so at 100% — the view a reader arrives at — the whole diagram is visible. The controls used to float over the frame's corners, which is exactly where a sequence diagram draws its first participant and a graph its leftmost node; no amount of nudging fixes that, because the picture is whatever shape its author drew. The row costs the height of one small button bar per diagram, which is the price of never covering the content.
Zooming in can still slide the diagram under the row's edge — the viewport clips it there — and that is deliberate: by then the reader is driving, and a frame that grew as you zoomed would reflow the page around it. The minimap, once opened, does float over the picture's bottom-left corner: the reader asked for it, and it closes with its own ✕.
| Input | What happens |
|---|---|
| Plain scroll wheel | Scrolls the page. Never intercepted. |
| Ctrl + wheel, or trackpad pinch | Zooms about the pointer |
| Drag | Moves the diagram, at any zoom level |
| One finger on a touchscreen | Scrolls the page |
| Two-finger pinch on a touchscreen | The browser's own page zoom |
| Toolbar buttons | Zoom out, zoom in, reset, maximize — plus fit, while maximized |
Cmd + wheel is deliberately not intercepted: on macOS that is the browser's own page
zoom, and taking it over would fight the platform.
Fit appears only while the diagram is maximized: it scales the diagram to fill the screen — the fitted view maximizing opens with — after you have zoomed or panned away from it. It is deliberately absent from the inline toolbar: the inline frame grows with the diagram, so at 100% everything is already visible and a fit would merely duplicate Reset.
The diagram viewport is focusable. Once focused:
| Key | Action |
|---|---|
+ or = |
Zoom in |
- or _ |
Zoom out |
0 |
Reset to 100% |
| Arrow keys | Pan |
| Shift + arrow keys | Pan by most of the viewport |
Keys with Ctrl, Cmd or Alt held are left to the browser, so shortcuts such as Ctrl + 0 keep
working, and Tab always moves on — the diagram is never a keyboard trap.
The toolbar buttons and the keyboard zoom about the top-left corner of the viewport, while the wheel zooms about the pointer. That difference is deliberate: a diagram rarely fills its viewport, and one that fits opens at the origin, so the empty space sits to its right and below. Zooming about the centre would scale that empty space and push the diagram off the top and left edges — most visibly when maximized. Anchoring at the top-left grows the diagram into the empty space instead and keeps it visible as long as possible.
Dragging moves the diagram whatever the zoom level — including a small one, and including a diagram that fits its frame whole. Maximize a modest diagram and it is fitted into a corner of the screen with room to spare; that space is now yours to move it into, rather than a grab cursor that did nothing.
Text inside a zoomable diagram is not selectable, because the same box is the drag surface:
the browser anchors a selection on the first press, before a drag can be told apart from a
click, so dragging used to paint the labels blue and leave them that way. The text is still
reachable everywhere it is actually read — the </> source view with its Copy button, the
diagram search, and the browser's find-in-page. A diagram with zoom=false is not a drag
surface and stays selectable, and a site that wants the selection back everywhere can say
[data-plantuml-diagram] svg {user-select: text}.
The rule in both directions is that the diagram stays reachable: it can never be dragged so far that an edge comes inside the viewport, and never so far that it leaves the viewport altogether. Where there is no room — a picture exactly as wide as its frame — it does not budge on that axis, so a wide, short diagram still pans sideways while staying put vertically. The arrow keys move it the same way, and Reset puts it back where it opened.
Scale is limited to 0.25×–8×, and the view resets to 100% whenever the diagram source or the site colour mode changes.
The lens button opens a search bar beside the toolbar. Matching is a case-insensitive substring search over the rendered SVG's text, so what you see is what you are searching. Every match is highlighted, the current one distinctly; the counter shows where you are; Enter / the chevrons step through the matches, Shift+Enter steps backwards, and each step pans the view so the match is centred — at whatever zoom level you are on. Escape or ✕ closes the bar and removes every highlight.
Matches are marked with data-plantuml-search-match (and the current one additionally with
data-plantuml-search-current) and coloured from the stylesheet, so site CSS can restyle the
highlight without touching the plugin.
The minimap button in the toolbar opens a minimap: a small copy of the diagram with a rectangle marking what the viewport currently shows. It appears in the diagram's bottom-left corner — the opposite one from the toolbar, so the control that opens it never covers it. Press or drag anywhere on the map to centre the view there — a single press works as "jump there". The map follows every zoom, pan and resize, works while maximized, and closes from its own ✕ or the toggle.
The map is pointer-only and hidden from assistive technology on purpose: the real viewport is already keyboard-operable with the arrow keys, so announcing a second, duplicated view of the same diagram would add noise without adding a capability.
The maximize button expands the diagram to fill the browser viewport over an opaque background, opening at the fitted scale — magnified or shrunk so the whole diagram fills the screen. The fit button (present only in this view) returns to that scale after zooming or panning. Escape or the maximize button restores the inline view, along with whatever zoom level you had before.
It is the last button in the toolbar, in both views. It is the only control whose
neighbours come and go — fit arrives with the maximized view, search and the minimap toggle
leave with the source — so anywhere in the middle it would shift under the pointer between
clicks. At the end it holds still, and the ✕ that closes the maximized view sits where a
reader looking to close something looks first.
This is an in-page overlay rather than the Fullscreen API. requestFullscreen() takes the
entire browser window fullscreen in Firefox instead of presenting the element, and its
::backdrop sits outside the element so the page shows through behind the diagram. An overlay
has neither problem, behaves identically in every browser, and needs no capability detection —
so the control also works on iOS Safari, which has no element fullscreen at all.
Globally:
['@matfsw/docusaurus-plantuml-plugin', {zoom: false}];Or for a single fence, which overrides the option either way:
```plantuml title="Small diagram" zoom=false
@startuml
Alice -> Bob : Hello
@enduml
```A reader who needs to zoom is rarely the author who would have enabled it, so leaving it off would mean most readers never discover it. The costs are real and worth knowing:
- Each zoomable diagram adds a keyboard tab stop for the viewport and one per toolbar button. On a page with six diagrams that is a meaningful amount of tabbing.
- The frame is one button-bar row taller than the picture, because the controls sit above it rather than over it — see The frame's layout.
- The rendered markup gains a viewport and transform wrapper around the
role="img"container. Site CSS that targets[data-plantuml-diagram] > div[role="img"]as a direct child needs updating — see Accessibility for both shapes. - Each diagram costs one non-passive
wheellistener and oneResizeObserver, and only in thereadystate.
Setting zoom: false restores the previous markup exactly.
Every rendered diagram offers its own source. The </> control in the toolbar flips the
frame: the source takes the diagram's place, in the same box. A Copy button appears beside
it in the same toolbar while the source is shown. Press </> again to flip back.
```plantuml title="Readers can copy this"
@startuml
Alice -> Bob : Hello
@enduml
```Details worth knowing:
- The source shares the diagram's frame. It was previously rendered below the diagram, which had two failure modes: a diagram taller than the window pushed it off-screen, so the control looked broken; and while maximized it was painted behind the full-screen overlay, so it was invisible however far you scrolled. In the frame it appears exactly where the picture was.
- The diagram is hidden, not unmounted. The frame keeps its height, so nothing on the page moves when you flip, and your zoom and pan survive the round trip.
- The zoom controls step aside while the source is shown — they would act on a picture nobody can see. Maximize stays, because it sizes the frame the source is read in, and taking it away while maximized would leave Escape as the only way out.
- The source stays outside the
role="img"subtree, which is opaque to assistive technology — content inside it would be unreachable for screen-reader users. - The copy result is announced through a
role="status"region, not by renaming the button. A control whose accessible name changes is announced as a new control every time. - A failed copy says so.
navigator.clipboardis undefined outside a secure context, which a docs site served over plain HTTP genuinely is. The panel is open either way, so the reader can select the text; the control never silently does nothing. - The panel shows the authored source, never the rendered SVG.
Turn it off for a whole site with showSource: false, or for one fence:
```plantuml showSource=false
@startuml
Alice -> Bob : Hello
@enduml
```With zoom: false there is no zoom toolbar, so the control gets its own row after the diagram.
Setting both zoom: false and showSource: false restores the bare markup the plugin produced
before either feature existed.
This is separate from showSourceOnError, which offers the source in the error panel when a
diagram fails to render.
A node (or edge) can carry a link — to an external site, another docs page, or another diagram's node via a deep link. What to write differs by engine.
Recommended form — give the node an alias and put the link on the same line:
```plantuml
@startuml
component "Order Service" as ORDER_SVC [[/docs/orders#graph?highlight-node=ORDER_DETAIL_1]]
' The same through a C4 macro — the alias is the macro's first argument:
!include <C4/C4_Container>
Container(billing, "Billing", "Java") [[/docs/billing#graph?highlight-node=INVOICE_QUEUE]]
@enduml
```The bundled engine parses [[url]] but emits no <a> elements, so the plugin
synthesizes the anchor: it reads the link back out of the fence source and wraps the
rendered element in a real anchor — clickable, keyboard-focusable, coloured with the site's
link colour, underlined on hover, and marked data-plantuml-diagram-link for site CSS. The
alias is the correlation key (the engine writes it into the SVG as data-qualified-name),
which is what makes this form work in every diagram — including ones whose
!include <…> shifts the engine's internal line numbering.
Fallback form — no alias. A plain quoted declaration or an edge label also works:
```plantuml
@startuml
component "Order Service" [[/docs/orders#graph?highlight-node=ORDER_DETAIL_1]]
"Order Service" --> "Billing" : invoices [[/docs/billing]]
@enduml
```With nothing alias-shaped on the line, the plugin correlates by the line number the engine
stamps on each element (data-source-line) — which is exact only in diagrams without
!include. In a standard-library diagram these links attach to nothing; use the aliased
form there.
Boundaries, by design: hrefs pass a scheme allowlist (http(s), site-relative, #… —
anything else is dropped); links inside note bodies stay the styled-but-inert text the
engine renders; one link per source line is correlatable; and a link that cannot be
correlated attaches to nothing rather than to the wrong node.
One form, no fallback involved — the engine emits the anchor itself, preserved through
sanitization (javascript: URLs are stripped):
```dot
digraph {
orders [URL="/docs/orders#graph?highlight-node=ORDER_DETAIL_1", label="Order Service", fontcolor=blue];
}
```Both engines share the same navigation behaviour: a click on an in-diagram link to a URL
this build routes goes through the Docusaurus router — no full page load — and
site-absolute paths get the site's baseUrl exactly as markdown links do, so /docs/orders
means the same thing in a diagram as in prose. External links and pure #… anchors stay
native, modified clicks (Ctrl, Cmd, Shift) keep the browser's own behaviour, and a click that
ends a drag never navigates.
A same-origin path this build has no route for stays native too, and that exception matters if your site is published as more than one Docusaurus build — one per product area, a docs build beside a marketing build, or two builds stitched together by a reverse proxy. Those bundles share an origin but each routes only its own subtree, so pushing a sibling build's path into this build's router would render this build's "Page not found" while the server that could serve it is never asked. (The tell is that reloading the same URL works.) The plugin checks the running build's route table and hands anything it does not own to the browser. An unknown page inside a subtree this build does own still routes normally — its own 404 page is the right answer there.
Clicking either example node above therefore navigates — without a reload — to
/docs/orders, where the diagram containing ORDER_DETAIL_1 highlights and centres it.
Rule of thumb: in PlantUML, give a node an alias if you link it or link to it. The
aliased spelling is immune to includes on both ends — as the outgoing link's correlation
key here, and as the incoming deep link's data-qualified-name target below. The
unaliased form exists so quick, plain diagrams work without ceremony.
A URL hash of the form #graph?highlight-node=REACTION_1234 focuses a node:
-
Every diagram on the page reacts - no diagram needs an id of its own. A diagram that does not contain the node simply does nothing.
-
The page scrolls to the first matching figure, the node is visibly highlighted (
data-plantuml-focused-node), and a zoomable diagram snaps to 100% centred on the node. The highlight stays until the hash changes. It uses the theme's success green by default; set--plantuml-focus-colorin site CSS to pick any other colour::root { --plantuml-focus-color: #3578e5; /* a light blue instead */ }
-
The hash is watched live, so following a
#graph?…link anywhere on the page - including one inside a Graphviz diagram - focuses the node without a reload. -
A
#graph?…hash defeats lazy loading for the page's diagrams, so a target below the fold still reacts. That costs the render of every diagram on the page, exactly aslazy: falsewould.
The identifier is resolved per diagram through a ladder; the first level that matches wins:
| # | Level | Works in | Authoring |
|---|---|---|---|
| 1 | Explicit SVG id |
Graphviz | node [id="REACTION-1234"] |
| 2 | PlantUML alias | PlantUML | component "X" as REACTION_1234, note "…" as REACTION_1234 - the alias lands in the SVG as data-qualified-name |
| 3 | Self-anchor link | Graphviz | node [URL="#graph?highlight-node=REACTION-1234"] - carries the id and, being a real link, clicking the node mints its own permalink |
| 4 | Node name | Graphviz | plain DOT node names, via the <title> Graphviz emits |
| 5 | Multiline label | both | %0A encodes the newline: #graph?highlight-node=Archive%0A12345 matches consecutive label lines, kept within one node's group |
| 6 | Substring | both | any text line containing the identifier, case-insensitively |
Level 2 is the PlantUML spelling of a hidden, deterministic id: the alias never appears in
the picture, but the engine writes it onto the entity's group - and aliased notes get
one too, so note "…" as MYNOTE_123 makes the note itself navigable. PlantUML aliases are
identifiers: use underscores (REACTION_1234), not hyphens, which do not parse.
Level 6 is what makes an unannotated node reachable by the unique part of its label - for a
node labelled caminus-process-archive\n12345, the hash #graph?highlight-node=12345
suffices. Levels 1-4 exist so that a deterministic, author-chosen identifier always beats
loose text matching.
With lazy: true (the default), a diagram is not rendered until it scrolls within 300 px of
the viewport, observed with IntersectionObserver. Consequently:
- The ~8 MB PlantUML runtime is fetched only on pages that actually contain a diagram, and only once such a diagram approaches the viewport.
- Diagrams far down a long page cost nothing until the reader gets there.
If IntersectionObserver is unavailable (older browsers, some test environments), the
component renders immediately rather than staying blank forever.
Set lazy: false to start rendering every diagram as soon as it mounts.
Rendered SVG is cached under a deterministic key:
<coreVersion>|<light|dark>|<san|raw>|<sourceLength>|<FNV-1a hash of source>
Everything that can change the output is in the key: the @plantuml/core version (so an
engine upgrade invalidates every entry), the colour mode, whether the output was sanitized,
and the source itself. The source length is included alongside the 32-bit hash so that a hash
collision alone cannot serve the wrong diagram.
| Mode | Behaviour |
|---|---|
'none' |
Nothing is stored. Every mount re-renders. |
'memory' |
Default. Process-lifetime Map, LRU-evicted down to cacheMaxEntries (50). Cleared on full page load. |
'session' |
sessionStorage under plantuml-client: keys, FIFO-trimmed to cacheMaxEntries. Survives client-side navigation and reloads within the tab. |
The cache is shared by every diagram on the page, so the same source rendered twice is rendered once. A cache hit skips the render queue entirely.
sessionStorage is treated as best-effort: entries that fail to parse or carry the wrong
entry version are discarded and re-rendered, and if sessionStorage throws at all (private
browsing modes, quota exhaustion, embedded browsers) the cache silently degrades to an
in-memory cache for the rest of the session. A storage failure never breaks rendering.
With zoom: false, a diagram renders as:
<figure
aria-busy="true"
data-plantuml-diagram="plantuml"
data-plantuml-status="rendering"
data-plantuml-theme="light"
>
<div role="img" aria-label="Authentication sequence"><svg>…</svg></div>
<figcaption>Authentication sequence</figcaption>
<noscript><pre>@startuml …</pre></noscript>
</figure>With zoom enabled (the default), the same role="img" element is wrapped by a viewport and a
transform layer, and a control group is added beside it:
<figure
data-plantuml-diagram="plantuml"
data-plantuml-status="ready"
data-plantuml-theme="light"
data-plantuml-interactive="true"
>
<div class="stage">
<div class="viewport" tabindex="0" aria-describedby="…" data-plantuml-zoom="1">
<div class="layer">
<div role="img" aria-label="Authentication sequence"><svg>…</svg></div>
</div>
</div>
<div role="group" aria-label="Authentication sequence zoom controls">…buttons…</div>
</div>
<p class="visuallyHidden" id="…">Zoomable diagram. Use the zoom controls, …</p>
<figcaption>Authentication sequence</figcaption>
<noscript><pre>@startuml …</pre></noscript>
</figure>div[role="img"] > svg holds in both shapes, so a selector written against it keeps working.
- The fence
title="..."becomes the<figcaption>and thearia-label. Without a title, the accessible label falls back toPlantUML diagram. - Progress is conveyed with
aria-busyon the<figure>, deliberately not with anaria-liveregion: a page with a dozen diagrams would otherwise announce a dozen state changes and make the page unusable with a screen reader. - Errors are announced once, through
role="alert"on the error panel. - Failure is never signalled by colour alone — the panel carries a literal
Error:label and a ⚠ glyph in addition to the danger colouring, so it survives colour-blindness and forced-colours mode. - Readers without JavaScript get the diagram source in a
<noscript>block. - The spinner animation is disabled under
prefers-reduced-motion: reduce, as is the easing of discrete zoom steps. Dragging and wheel zooming stay instantaneous either way, because direct manipulation is not decoration. - Zoom controls live outside the
role="img"element. That role makes its whole subtree opaque to assistive technology, so a button placed inside would be invisible to screen-reader users. - The control group is
role="group", notrole="toolbar": the toolbar role obliges arrow-key navigation between its buttons, and the arrow keys already pan the diagram. - Button labels are static and the zoom percentage is
aria-hidden. A live percentage would announce on every wheel tick. - Keyboard instructions are attached to the viewport with
aria-describedbyrather than being announced on focus repeatedly.
These attributes are part of the public surface; write your own end-to-end tests against them.
| Attribute | Values |
|---|---|
data-plantuml-diagram |
the fence language that matched, e.g. plantuml, puml, dot |
data-diagram-engine |
plantuml | graphviz |
data-diagram-layout |
Graphviz layout engine, e.g. dot; absent on PlantUML diagrams |
data-plantuml-status |
idle | loading | rendering | ready | error |
data-plantuml-theme |
light | dark |
data-plantuml-interactive |
true, on the <figure>, only when zoom is enabled |
data-plantuml-zoom |
current scale on the viewport, e.g. 1, 2.5 |
The data-plantuml-* prefix is historical: it predates Graphviz support and is applied to
every diagram this plugin renders, whatever the engine. It was kept rather than renamed so that
existing author CSS and end-to-end tests keep working. Select on data-diagram-engine when the
two engines need different styling.
PlantUML output is generated from diagram source, and diagram source can express markup —
labels, <style> blocks, hyperlinks. The rendered SVG is therefore treated as untrusted and,
by default, passed through DOMPurify before it reaches the DOM:
USE_PROFILES: {svg: true, svgFilters: true}— geometry, text, gradients, filters, markers and links survive.- Additionally forbidden:
foreignObject,script,iframe,object,embed,audio,video.foreignObjectmatters most: it is the one SVG element that can host arbitrary HTML, which would reintroduce precisely the injection surface the SVG profile exists to remove. PlantUML does not need it. formaction,xlink:showandpingattributes are dropped;roleand thearia-label/aria-labelledby/aria-describedbyattributes are preserved so the diagram stays accessible.- Event-handler attributes (
onload,onclick, …) andjavascript:URLs are removed by DOMPurify itself.
If sanitization removes so much that no <svg> root remains, the plugin raises an error
rather than showing a silently blank figure.
sanitizeSvg: false is a supported, documented opt-out — and a genuine risk. With it off,
whatever HTML or JavaScript a diagram author can express in PlantUML's output is injected
into your page verbatim and executes with your site's origin, cookies and storage. Turn it
off only if every diagram source in your site is fully trusted — that is, if nobody who could
not already commit arbitrary code to the site can influence a diagram. If you accept diagrams
from external contributors, from generated content, or from anything user-supplied, leave it
on.
Nothing. The engine is copied into your own build output and served from your own origin; the renderer calls it in-process and inserts the result into the DOM. There is no HTTP fallback to plantuml.com or anywhere else, and none can be configured.
A failed diagram produces a contained error panel. It never crashes the page, never blocks the render queue, and never silently disappears.
The panel shows a heading naming the engine (⚠ Error: PlantUML diagram could not be rendered,
or ⚠ Error: Graphviz diagram could not be rendered), the message, and — unless
showSourceOnError: false — the original source in a collapsed <details> element. The
wrapper carries data-plantuml-status="error".
Failures are classified internally as one of:
| Kind | Cause |
|---|---|
load |
viz-global.js or plantuml.js could not be fetched, timed out, or was not the expected module (usually a proxy or service worker returning the wrong file). |
engine |
The engine threw, or its output could not be used at all. Includes Diagram too large for browser rendering: WxH (max 32768; …) — see Diagram size. |
diagram |
The source is not valid PlantUML. |
syntax |
The source is not valid DOT. Carries Graphviz's own diagnostic, including the line number. |
too-large |
A DOT source exceeded graphviz.maxSourceBytes. |
stdlib |
A !include <namespace/…> names a standard library namespace this site does not provide, or the standard library is switched off. See Standard library. |
timeout |
One render exceeded renderTimeoutMs. |
config |
The plugin's global data is missing, or a fence named a layout engine this Graphviz build does not have. |
aborted |
The component unmounted or re-rendered; not surfaced to the reader. |
The two engines report invalid source very differently:
- Invalid PlantUML is not reported through the engine's error callback. The engine renders an "error picture" and reports success, so the rendered SVG is inspected for error markers before it is trusted. See ADR 0002 for the exact detection rules.
- Preprocessor failures carry no
Syntax Error?marker at all —Function not found Xafter a macro that the included library version does not define, orcannot include <C4/C4_Nope>for a file that is not in the namespace. Both are detected by their own signature, and the panel shows the failure rather than the expanded source it sits in. - Invalid DOT is reported as structured data, so the panel shows Graphviz's own message
verbatim —
syntax error in line 3 near '}'— with no heuristics involved.
@plantuml/core measures every diagram it lays out and refuses to serialize one wider or
taller than a set number of PlantUML points, reporting it through its error callback:
Diagram too large for browser rendering: 78x12916 (max 8192; override via the maxSvgSize
option, or set it to 0 to disable this check)
The engine's own ceiling is 8192. This plugin sets 32768 by default — high enough that
a real architecture diagram or release runbook does not meet it — and maxSvgSize moves it:
{
maxSvgSize: 65_536, // raise it
}{
maxSvgSize: 0, // no ceiling at all
}It takes a non-negative integer. 0 is the engine's own convention for "no check"; a negative
value is rejected at build time rather than passed through, because the engine reads a negative
as "unspecified" and would quietly fall back to 8192.
The ceiling is not something a diagram can talk its way around, which is why the option is the only real lever. Measured against the engine:
| Attempt | Effect |
|---|---|
scale 0.3 |
none — the check reads the pre-scale dimensions |
skinparam dpi 40 |
none — dpi affects raster output, not this measure |
left to right direction |
none; it transposes width and height |
skinparam ranksep 5 |
works — it genuinely shrinks the layout |
So if you would rather keep the ceiling where it is, the levers that work are the ones that
make the diagram smaller: fewer nodes and edges, tighter skinparam ranksep/nodesep, a
smaller skinparam defaultFontSize, or splitting one diagram into several fences.
Raising it is not free. A 30 000-point diagram is a multi-hundred-KB SVG, and both the
error detection and the DOMPurify sanitization parse it synchronously on the main thread. Such
a diagram can visibly stall the tab while it lands, and may need renderTimeoutMs raised above
its 20 s default. That cost is the reason the default is a number rather than 0. See
ADR 0008.
maxSvgSize applies to PlantUML fences only; Graphviz has its own guard in
graphviz.maxSourceBytes.
The runtime assets are emitted into
<baseUrl>assets/plantuml-client-<coreVersion>/
and resolved in the browser through Docusaurus' own useBaseUrl(). A site deployed at
baseUrl: '/plantuml-test/' therefore fetches:
/plantuml-test/assets/plantuml-client-1.2026.8/viz-global.js
/plantuml-test/assets/plantuml-client-1.2026.8/plantuml.js
No path is hard-coded to the site root, so project-pages deployments and reverse-proxied
subpaths work without configuration. The engine version is part of the directory name, so an
upgrade changes the URL and stale caches are defeated automatically. The bundled example site
deploys under a non-root baseUrl precisely so this path is exercised on every build.
The runtime requires:
- ES modules and dynamic
import() AbortControllerMutationObserverIntersectionObserver— optional; a graceful fallback renders immediately when it is absentsessionStorage— optional; only forcache: 'session', which degrades to memory without it- Pointer Events — required for drag-to-pan when
zoomis enabled ResizeObserver— optional; without it zoom still works, but the view is not re-clamped when the column is resized
It requires no particular fonts. The toolbar's controls are inline SVG rather than symbol
characters, which they were until 1.3.1: ⛶ U+26F6 (maximize) has no glyph in any font a stock
Linux desktop ships, so it rendered as an empty box for those readers, and the rest only worked
where DejaVu Sans happened to be installed. The icons inherit currentColor and 1em, so they
follow the colour mode and the reader's font size the way the characters did.
That is modern evergreen Chrome, Edge, Firefox and Safari. Internet Explorer is not supported and will not be.
Nothing in this plugin affects readers on pages without diagrams — for them the site behaves exactly as it did before installation.
The runtimes are large:
| File | Size (uncompressed) | Needed for |
|---|---|---|
plantuml.js |
≈ 6.8 MB | PlantUML fences only |
viz-global.js |
≈ 1.4 MB | DOT fences, and PlantUML's own layout |
| Total | ≈ 8.2 MB |
Standard library namespaces are separate again, and much smaller: one bundle per namespace, 5 to 220 KB gzipped, fetched only by the pages whose diagrams include them. A C4 page adds 29 KB to the figures above; a page with no standard library include adds nothing.
Crucially, none of that is in your site's initial bundle. The files are emitted as static
assets, not imported into the webpack graph (the dynamic import is marked webpackIgnore), so:
- Pages with no diagram never request them.
- Pages with diagrams request them once, on first render — and with
lazy: true, only when a diagram nears the viewport. - Each runtime is requested only if a diagram actually needs it. A page with only DOT
diagrams fetches
viz-global.jsand never the 6.8 MB PlantUML engine; a page with PlantUML diagrams fetches both, because PlantUML needs Graphviz for its own layout. - The files are served from your origin with your own cache headers, and are re-fetched only when the engine version changes.
Adding Graphviz support to a site that already renders PlantUML costs nothing, because
viz-global.js was already being emitted and loaded.
The published npm package is the compiled plugin, its theme components, and ~3 MB of vendored
standard library bundles; the 8 MB engine comes from the @plantuml/core dependency. Both land
in your build output rather than in your JavaScript bundle, so budget for roughly 11 MB of
extra static assets per deployed site — of which a given reader downloads the 8 MB engine once
and only the standard library namespaces their pages actually use. stdlib.namespaces narrows
what is emitted if the build output size matters more to you than which diagrams keep working.
Serve these assets with compression enabled — they are ordinary JavaScript and compress well.
Everything is same-origin. You need no connect-src entry for any third party, no CDN
allowance, and this plugin's own code uses no eval or new Function.
What you do need:
script-src 'self';
viz-global.js is injected as a classic <script> element pointing at your own origin, so
'self' must be allowed for scripts. plantuml.js is then loaded with a dynamic import()
of a same-origin URL.
You may additionally need:
script-src 'self' 'wasm-unsafe-eval';
The engine is asm.js/TeaVM-compiled JavaScript plus Viz.js. Depending on the engine build and
how your CSP treats WebAssembly compilation, 'wasm-unsafe-eval' may be required — treat
this as "add it if diagrams fail with a CSP error mentioning WebAssembly", not as a
certainty. If you use a nonce- or hash-based script-src, note that the injected
<script> element is created at runtime and will not carry your nonce; a 'self' source
expression is the straightforward configuration.
No unsafe-eval from this plugin's own code is required.
Clone the repository and install with npm ci. Node 20 or newer is required (see .nvmrc).
| Command | What it does |
|---|---|
npm run build |
Clean, tsc the ESM + theme output, tsup the CommonJS entry, finalize |
npm run clean |
Remove build output |
npm run typecheck |
tsc --noEmit over the whole project |
npm run lint |
ESLint |
npm run lint:fix |
ESLint with --fix |
npm run format |
Prettier write |
npm run format:check |
Prettier check |
npm test |
Unit and component tests (alias for test:unit) |
npm run test:unit |
vitest run |
npm run test:watch |
vitest in watch mode |
npm run test:coverage |
vitest run --coverage |
npm run test:integration |
Pack the tarball, install it into a clean fixture, build and serve it |
npm run test:e2e |
Playwright against the served fixture |
npm run test:all |
Format, lint, typecheck, unit, build, pack check, integration — the CI gate |
npm run pack:check |
Inspect npm pack --json output for missing or unexpected files and size drift |
npm run verify:tag |
Assert the pushed v<version> tag matches package.json |
npm run sync:meta |
Propagate project.config.json into every file that repeats the project identity |
npm run sync:check |
Fail if any derived file has drifted (run in CI) |
npm run example:install |
Install the example site's dependencies |
npm run example:start |
Docusaurus dev server for the example site |
npm run example:build |
Production build of the example site |
npm run example:serve |
Serve the example site's production build |
Project identity lives in project.config.json — package name, GitHub repository, plugin id,
licence, description. Change the one line you need and run:
npm run sync:metaThis rewrites package.json, the example site's dependency and docusaurus.config.ts.
npm run sync:check fails the build if anything has drifted.
The internal Docusaurus plugin name — docusaurus-plugin-plantuml-client, the key under
which the plugin publishes its global data — is deliberately independent of the npm
package name, so renaming the package cannot break global-data lookups in already-built sites.
Four layers, all deterministic and none of them calling an external PlantUML service:
- Unit and component tests (Vitest + jsdom). Language detection and case handling,
delegation of non-PlantUML blocks, fence source and title extraction, option defaults and
validation, singleton asset loading and concurrent load deduplication, loader failure and
retry, FIFO queue ordering, queue continuation after failure, timeouts, unmount during
render, light/dark cache separation, memory cache eviction,
sessionStoragefailure and corruption handling, SVG sanitization against synthetic malicious input, the loading/ready/ error UI, SSR without browser globals, theIntersectionObserverfallback, and the zoom layer: focal-point and clamping geometry as pure functions, the wheel policy (plain wheel ignored, Ctrl honoured, Cmd ignored), keyboard handling, both reset triggers, and listener teardown. For Graphviz specifically: the nested option group and its validation including the both-engines-claim-one-language check,engine=metastring parsing, the separate cache-key namespace and its deliberate omission of the colour mode, structured error formatting and line-number extraction, thewindow.VizAPI assertion, the loader split (a DOT-only page never importing the PlantUML module), the source-size guard measuring UTF-8 bytes before loading anything, engine reuse across renders and across syntax errors, that a colour-mode toggle re-renders a PlantUML diagram but not a Graphviz one, and that DOMPurify stripsjavascript:from DOT'sURL=links while preserving the colour attributes the dark-mode CSS selects on. Docusaurus@theme/*and@docusaurus/*aliases only exist inside a real Docusaurus webpack build, so the Vitest config points them at local stubs. - Package verification (
npm run pack:check). Runsnpm pack --dry-run --json, prints the file list with sizes, and fails on missing compiled files or declarations, a missing README or LICENSE, published tests, source maps, example build output, nested tarballs, CI configuration,exportsentries pointing at unpacked files, or size budget overruns. - Packed-tarball integration (
npm run test:integration). Builds the package, runsnpm pack, installs the resulting.tgz— not a workspace link — into a clean Docusaurus fixture in a temporary directory, runs a fulldocusaurus build, and serves it. This is what proves the package works as consumers actually install it. - Browser end-to-end (
npm run test:e2e, Playwright against the served production build). Asserts that zooming magnifies the diagram without changing the figure's height, that a plain wheel scrolls the page while Ctrl + wheel zooms without scrolling, that the focal point stays under the cursor, that panning is clamped so an edge never comes inside the viewport, and thattouch-actionstayspan-y pinch-zoom. It also asserts that real<svg>elements appear inside the expected container with the expected diagram labels, that multiple diagrams render on one page, that.mdand.mdxboth work, that ordinary code blocks are untouched, that an invalid diagram produces the documented error state, that toggling dark mode re-renders, that client-side navigation away and back still works, that the runtime is not loaded on a diagram-free page and is loaded at most once when diagrams are present, that every asset URL carries the configuredbaseUrl, that no request goes to an external host, and that the build hydrates without React mismatch warnings. The Graphviz suite adds: DOT fences rendering to real SVG with the expected node labels, a DOT-only page fetchingviz-global.jsonce andplantuml.jsnever, both engines rendering on one page with one download each,engine=neatoandengine=circoproducing distinct layouts, the Graphviz diagnostic and its line number appearing in the error panel while the rest of the page still renders, default colours changing with the colour mode while authored colours do not, ajavascript:URL never surviving into a link, zoom working the same as it does for PlantUML, and a client-side navigation not re-downloading the engine.
The example site under examples/docusaurus/ is the fixture: it deploys under
baseUrl: '/plantuml-test/' and contains a sequence diagram, a Graphviz-dependent class
diagram, a component diagram, several diagrams on one page, .md and .mdx documents, a
puml alias, title metadata, an invalid diagram, an ordinary TypeScript block, a page with no
diagram at all, a Graphviz page exercising several layout engines and authored colours, and a
DOT-only page that proves the PlantUML engine is never fetched for it.
Releases are automatic. Nothing is run from a local checkout, and nothing is tagged by hand.
Every merge into main runs CI; when CI goes green, .github/workflows/release.yml reads
CHANGELOG.md and decides whether the merge warrants a release and at what level:
## [Unreleased] contains |
Release |
|---|---|
### Removed, or the word BREAKING |
major |
### Added |
minor |
any other section (Fixed, Changed, Security) |
patch |
| nothing, but only dependency bumps since the tag | patch |
| nothing else | none |
That is why CONTRIBUTING.md insists on a ## [Unreleased] entry in every pull request: the
entry is what sets the version. Dependency-only merges need no entry — the workflow writes one
from the commit subjects.
Having decided, the workflow runs scripts/next-release.mjs, which bumps package.json and
package-lock.json, closes ## [Unreleased] into a dated section, opens a fresh empty one and
adds the compare link at the foot of the changelog. It then pushes the Release <version>
commit and the v<version> tag atomically — both land or neither does, so a tag can never
describe a tree that is not on main. If main moved underneath, it rebuilds the release from
the new main rather than forcing anything.
To release a specific version, or to see what would happen without touching anything:
gh workflow run release.yml -f dry_run=true # decide and print, push nothing
gh workflow run release.yml -f version=2.0.0 # release a version explicitlyPushing v<version> runs .github/workflows/publish.yml, which:
- Installs cleanly with
npm ci. - Runs formatting, lint, type checking, unit tests, the build, the package verification and the packed-package Docusaurus integration test. No publish happens until all of them pass.
- Runs
scripts/verify-tag-version.mjs, which fails the release if the tag does not exactly match theversioninpackage.json(tagv1.2.3⇒ version1.2.3). - Publishes with
npm publish --access public— the package is scoped, so--access publicis required for the first and every subsequent publish. - Creates the GitHub Release, with that version's changelog section as its notes. This runs only after npm has accepted the publish, so a GitHub Release never exists without the npm release behind it.
Prereleases follow the same path: a version like 1.2.3-beta.1 is published under a
non-latest dist-tag, so npm install @matfsw/docusaurus-plantuml-plugin keeps resolving to
the last stable release.
Authentication is npm trusted publishing over GitHub Actions OIDC. There is no long-lived
npm token anywhere in this repository, in its workflows, or in its secrets. The workflow runs
in a GitHub environment named npm, so maintainers can require manual approval before a
release proceeds — that environment is the one place to put a brake on the automation.
Provenance is attested automatically by trusted publishing.
The release commit and the tag are pushed with a GitHub App installation token rather than
GITHUB_TOKEN, because a push made with GITHUB_TOKEN triggers no further workflow runs — the
tag would sit there and publish.yml would never fire. See
docs/adr/0006-automated-release-from-changelog.md.
Do this once, as the npm package owner. It is not needed for day-to-day contribution.
- Create the package on npm. Trusted publishing is configured per package, so the
package must exist first. Publish the initial version manually (
npm publish --access publicfrom a local checkout with a personal login) or create it through whatever bootstrap process you prefer. - Open the package settings on npmjs.com —
https://www.npmjs.com/package/@matfsw/docusaurus-plantuml-plugin→ Settings. - Add a trusted publisher and choose GitHub Actions as the provider.
- Enter the owner and repository: owner
matf, repositorydocusaurus-plantuml-plugin. They must match the GitHub repository exactly. - Enter the workflow filename:
publish.yml. This is the filename only, not.github/workflows/publish.yml. npm matches on the filename, which is why the workflow file must never be renamed. - Set the environment name:
npm. It must match theenvironment:in the workflow. - Allow
npm publishfor this trusted publisher. - Confirm
package.jsonrepository.urlmatches the GitHub repository exactly —git+https://github.com/matf/docusaurus-plantuml-plugin.git. Provenance verification compares it.npm run sync:metakeeps it correct. - Enable publishing-access restrictions once you have verified a trusted-publish actually works: in the package settings, require two-factor authentication or trusted publishing for publication, so no token can publish behind your back.
- Remove obsolete automation tokens. Any granular or classic token that existed only to publish this package should be deleted from your npm account.
Trusted publishing authenticates publication. It does not provide credentials for installing private dependencies. This repository has no private dependencies, so do not add a read token to CI. Add one only if the repository genuinely starts consuming a private package.
release.yml and dependabot-auto-merge.yml push and merge with a GitHub App installation
token rather than GITHUB_TOKEN. This is not a preference: GitHub deliberately does not trigger
workflow runs from events created with GITHUB_TOKEN, so under that token an auto-merge would
not run CI on main and a pushed tag would not run publish.yml. Nothing would ever reach npm.
Done once, by a repository admin:
- Create a GitHub App owned by the repository owner, with the webhook inactive.
- Repository permissions, and nothing else: Contents Read and write (push the release commit and tag), Pull requests Read and write (enable auto-merge, comment, update a branch), Metadata Read-only (mandatory).
- Install it on this repository only, and generate a private key.
- Store the credentials under Settings → Secrets and variables → Actions:
RELEASE_APP_IDandRELEASE_APP_PRIVATE_KEY(the whole.pem, BEGIN/END lines included). - Add the App as a bypass actor on the
mainruleset. A ruleset's required-status-checks rule blocks direct pushes as well as merges, and the release commit is a direct push. The safety net ispublish.yml, which re-runs the entire suite on the tagged tree beforenpm publish, so a bad release commit cannot reach npm even though it can reachmain.
Installation tokens are repo-scoped and expire in an hour. A personal access token would work too and was rejected: it carries one person's account reach and expires on a calendar.
- A theme providing
MDXComponents/Codemust already be installed. The plugin wraps that component via@theme-init/; with no underlying implementation there is nothing to wrap.@docusaurus/theme-classic(viapreset-classic) satisfies this. - A site-level swizzle of
MDXComponents/Codewins. If your site swizzles that component itself, the site's version is what Docusaurus uses and this plugin is bypassed. - Two plugins wrapping the same component do not compose. If another plugin also wraps
MDXComponents/Code, only one wrapper survives. See ADR 0001. docusaurus swizzleis not supported for this plugin's components.getTypeScriptThemePathis intentionally not implemented, to keep the published package lean. Fork the component if you need to change it.- Code blocks authored as JSX children are not intercepted. When a fence's children contain React elements rather than plain text, the source cannot be recovered reliably, so the block is handed back to the original component untouched.
- Diagrams are not rendered during static-site generation. The HTML Docusaurus emits
contains the deferred placeholder and the
<noscript>source. Search engines that do not execute JavaScript will not see the diagram image. - PlantUML links inside note bodies are not clickable. The plugin synthesizes the
[[url]]anchors the bundled engine drops on components, participants, macros and relations — but a link in a note's text renders as the styled-but-inert text the engine emits, with nothing to correlate it to. One link per source line is correlatable, for the same reason. See Links and deep links. - One PlantUML diagram renders at a time. The PlantUML engine has module-level shared state, so a page with many large diagrams renders them sequentially. This is a correctness requirement, not a tuning knob. Graphviz has no such constraint and is not queued.
- PlantUML diagrams are capped at 32768 points in each dimension by default. The engine
measures the laid-out diagram and refuses anything larger.
maxSvgSizeraises the ceiling, or removes it with0— see Diagram size — but a genuinely enormous diagram then renders instead of failing fast, and both the error detection and the sanitizer parse the resulting SVG synchronously, so it can stall the tab on its way in. Past that, the diagram itself has to get smaller. - A
@plantuml/coreolder than1.2026.8fails the build. That release added themaxSvgSizerender option, and an engine that does not know the option ignores it in silence — which would leavemaxSvgSizereading as honoured while the engine's own ceiling refused large diagrams. The plugin checks the installed version rather than guessing. - Graphviz rendering blocks the main thread. Viz.js lays out synchronously. A 300-edge
graph takes ~26 ms, but a 3 000-edge graph takes ~2.25 s and visibly freezes the page;
graphviz.maxSourceBytesis the guard. Rendering in a Web Worker would remove the ceiling and is a possible future enhancement. themedoes not apply to Graphviz diagrams. Graphviz has no dark palette; its colours are adapted with CSS instead. See Light and dark mode.renderTimeoutMscovers both loading and rendering. On a very slow connection, the 8 MB download is subject to the same budget as a render.- Consuming the plugin through a
file:link needs a webpack tweak. See the entry in Troubleshooting below. - No pinch-to-zoom of the diagram itself on touchscreens. Two-finger pinch is deliberately left to the browser's own page zoom, so a full-width diagram can never become a scroll trap and page zoom is never taken away. Trackpad pinch on a laptop does zoom the diagram, because the browser reports it as Ctrl + wheel.
- Zoom state is not persisted. Navigating away and back, or switching colour mode, returns the diagram to 100%.
Open the network tab and check the failing URL. It should be
<baseUrl>assets/plantuml-client-<version>/viz-global.js. If the request goes to
/assets/... when your site lives at /docs/, the site's baseUrl is wrong — not the
plugin's paths, which are always resolved through useBaseUrl().
Docusaurus' baseUrl must be the deployment subpath with leading and trailing slashes:
baseUrl: '/plantuml-test/', not 'plantuml-test' or '/plantuml-test'. A wrong value
breaks the PlantUML assets the same way it breaks every other Docusaurus asset. Fix it and
rebuild.
If nginx, Apache or a CDN strips or rewrites a path prefix, the browser will request a URL
your origin does not serve. Make the proxy pass <baseUrl>assets/** through unmodified, and
verify by requesting the exact viz-global.js URL from the network tab with curl.
plantuml.js is loaded with a dynamic import(), and browsers refuse to execute an ES module
served as text/plain, application/octet-stream or text/html. The console shows a strict
MIME type checking error. Check with:
curl -I https://example.com/your-base-url/assets/plantuml-client-1.2026.8/plantuml.jsThe content-type must be a JavaScript type (text/javascript or
application/javascript). If you get text/html, the proxy is serving your SPA fallback
instead of the file — the file is not reaching the origin at all.
Symptom: a console message naming a violated directive, and diagrams stuck loading. Ensure
script-src allows 'self'; add 'wasm-unsafe-eval' if the violation mentions WebAssembly.
See Content Security Policy. No connect-src change for third
parties is ever needed, because nothing third-party is contacted.
@plantuml/core is an ~8 MB dependency and slow or MITM-ing proxies time out on it or serve
a truncated tarball. Symptoms are an install failure, an integrity mismatch, or a build-time
Could not resolve '@plantuml/core'. Configure npm config set proxy / https-proxy and
your corporate CA (npm config set cafile), raise npm config set fetch-timeout, and delete
node_modules plus the npm cache before retrying. On self-hosted GitHub Actions runners,
give the runner the same proxy and CA configuration.
Script-blocking and privacy extensions sometimes block large inline-compiled JavaScript, WebAssembly compilation or worker creation. If diagrams fail for one reader but work in a private window with extensions disabled, that is the cause. Ask the reader to allow-list the site.
Not this plugin. @docusaurus/bundler pinned webpackbar@^6.0.1 until Docusaurus 3.10.2,
and that version of webpackbar is rejected by webpack >= 5.109. Any Docusaurus
3.5–3.10.0 site fails this way from a fresh install, with or without this plugin
installed. Add "overrides": {"webpackbar": "^7.0.0"} to your site's package.json and
reinstall, or upgrade Docusaurus to 3.10.2 or later. See
Status and compatibility.
Symptom: the page fails with something like useColorMode is called outside the
ColorModeProvider, or React complains about invalid hook calls. This means two copies of
React or of @docusaurus/theme-common are loaded.
This bites specifically when the plugin is consumed through a local file: link. webpack
resolves symlinks to their real path by default, so the plugin's theme components resolve
@docusaurus/theme-common and react from the linked package's directory instead of from
the site — two module instances, two React contexts. The example site works around it with a
tiny inline plugin:
function resolveLinkedPluginFromSite() {
return {
name: 'example-resolve-linked-plugin',
configureWebpack() {
return {resolve: {symlinks: false}};
},
};
}A normal npm install from the registry has no symlink and needs none of this — which is
exactly what the packed-tarball integration test proves. If you hit this on a real install
instead, run npm ls react @docusaurus/core and dedupe.
The error panel shows PlantUML's own message (with the engine's version-nag lines stripped),
and the source is available under Show diagram source. Common causes: a missing @enduml,
a typo that makes PlantUML guess the wrong diagram type, or a diagram kind this engine build
does not implement. Paste the source into any PlantUML tool to confirm, and note that an
unterminated @startuml surfaces as a Java exception rather than a syntax error.
The asset directory carries the engine version, so an engine upgrade cannot be served from a stale cache. Your own site's JavaScript can be, though — particularly behind a service worker registered by a PWA plugin. Hard-reload, or unregister the service worker under Application → Service Workers in DevTools, before concluding that a fix did not land.
After upgrading the plugin, webpack's persistent cache in node_modules/.cache (and
.docusaurus/) can keep serving the previous version's theme components — you change the
plugin and nothing changes in the browser. This is a real failure mode we have hit. Clear it:
npx docusaurus clearThen rebuild. If it persists, remove node_modules/.cache and .docusaurus/ by hand.
docs/architecture.md— SSR boundary, asset loading, render queue, caching, sanitization, and how each engine handles dark mode.docs/adr/0001-theme-init-alias.md— why the plugin wraps@theme-init/, not@theme-original/.docs/adr/0002-render-to-string.md— why the string API is used instead of the DOMrender()API, and how invalid diagrams are detected.docs/adr/0003-zoom-container-transform.md— why zoom transforms a wrapper rather than the SVG.docs/adr/0004-graphviz-engine-reuse.md— why DOT is rendered with the Graphviz already inside@plantuml/core, and what that couples us to.docs/adr/0005-stdlib-bundles.md— how!include <C4/…>is resolved, why the engine's own loader has to be short-circuited, and how the vendored set was chosen.CONTRIBUTING.mdSECURITY.md
MIT. See LICENSE.