@matfsw/docusaurus-plantuml-plugin 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-08-14
+
+### Added
+
+- **Deep links *from* diagram nodes — including to diagrams on other pages.** A node can now
+  carry a link to another diagram's deep link, and clicking it navigates there and focuses
+  the target node: `component "Order Service" as ORDER_SVC
+  [[/docs/orders#graph?highlight-node=ORDER_DETAIL_1]]` in PlantUML, or
+  `orders [URL="/docs/orders#graph?highlight-node=ORDER_DETAIL_1"]` in Graphviz.
+
+  For PlantUML this means the plugin now **synthesizes the anchors the bundled engine
+  drops**: `[[url]]` on components, participants, C4 macros and relations is read back out
+  of the fence source and wrapped around the rendered element — clickable,
+  keyboard-focusable, marked `data-plantuml-diagram-link`, coloured with the site's link
+  colour. Correlation runs on the alias the engine writes into `data-qualified-name`, with
+  `data-source-line` as the fallback, so it survives `!include` — standard-library diagrams
+  included, whose preprocessing shifts every line number. Synthesized hrefs pass a scheme
+  allowlist; a link that cannot be correlated attaches to nothing. Links inside note bodies
+  remain the engine's styled-but-inert text, and one link per source line is correlatable.
+
+  Navigation is SPA-aware in both engines: in-diagram links to same-site URLs go through
+  the Docusaurus router — no full page load — and site-absolute paths get the site's
+  `baseUrl` exactly as markdown links do. External links and pure `#…` anchors stay native,
+  and clicks that end a drag never navigate.
+
+### Changed
+
+- **The deep-link highlight is green, not red.** The focused-node colour was the theme's
+  danger red, which reads as an error on a highlight that persists until the hash changes;
+  it now defaults to the theme's success green. Sites can pick any colour by setting
+  `--plantuml-focus-color` — the rule reads
+  `var(--plantuml-focus-color, var(--ifm-color-success))`.
+
 ## [1.4.0] - 2026-08-13
 
 ### Added
@@ -449,7 +482,8 @@ Initial release.
   opt-out.
 - Plugin option validation that rejects unknown keys and out-of-range values at build time.
 
-[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.4.0...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.2.0...v1.3.0

package/README.md

@@ -697,24 +697,86 @@ diagram _fails_ to render.
 
 ## Links and deep links
 
-### Links written in the diagram source
+### Linking from a node
 
-**Graphviz** emits real hyperlinks: `URL=`/`href=` on a node or edge becomes an `<a>` in the
-rendered SVG, preserved through sanitization (`javascript:` URLs are stripped). Links stay
-clickable inside the zoomable viewport: a plain click follows the link, while a click that
-ends a drag does not.
+A node (or edge) can carry a link — to an external site, another docs page, or another
+diagram's node via a [deep link](#deep-links-graphhighlight-node). What to write differs by
+engine.
+
+#### PlantUML
+
+**Recommended form — give the node an alias** and put the link on the same line:
+
+````markdown
+```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:
+
+````markdown
+```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.
+
+#### Graphviz
+
+One form, no fallback involved — the engine emits the anchor itself, preserved through
+sanitization (`javascript:` URLs are stripped):
 
 ````markdown
 ```dot
-digraph { docs [URL="https://graphviz.org/doc/info/attrs.html"]; }
+digraph {
+  orders [URL="/docs/orders#graph?highlight-node=ORDER_DETAIL_1", label="Order Service", fontcolor=blue];
+}
 ```
 ````
 
-**PlantUML** links are an engine limitation today: the bundled browser engine renders
-`[[url]]` link _text_ (styled blue and underlined) but emits no `<a>` elements, so PlantUML
-links are not clickable. Deep-link addressing does not depend on them - PlantUML nodes are
-addressed by alias, below. Should the engine gain anchor output, links will pass through
-sanitization unchanged (that path is pinned by tests, `target="_top"` included).
+#### How clicks navigate
+
+Both engines share the same navigation behaviour: a click on an in-diagram link to a
+same-site URL 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.
+
+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.
 
 ### Deep links: `#graph?highlight-node=…`
 
@@ -723,8 +785,16 @@ 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`, restylable from site CSS), and a zoomable diagram snaps to
-  **100% centred on the node**. The highlight stays until the hash changes.
+  (`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-color` in site CSS to pick any other colour:
+
+  ```css
+  :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
@@ -1253,10 +1323,11 @@ package.
 - **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 `[[url]]` hyperlinks are not clickable.** The bundled browser engine renders
-  the link text (styled blue and underlined) but emits no `<a>` elements into its SVG.
-  Graphviz links work; PlantUML deep-link addressing works through aliases and does not
-  need links. See [Links and deep links](#links-and-deep-links).
+- **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](#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.

package/dist/constants.d.ts

@@ -51,4 +51,6 @@ export declare const DATA_ATTR: {
     readonly searchCurrent: "data-plantuml-search-current";
     /** On the node (or its text lines) a `#graph?highlight-node=…` deep link resolved to. */
     readonly focusedNode: "data-plantuml-focused-node";
+    /** On anchors the plugin synthesized from `[[url]]` links the PlantUML engine dropped. */
+    readonly diagramLink: "data-plantuml-diagram-link";
 };

package/dist/constants.js

@@ -53,4 +53,6 @@ export const DATA_ATTR = {
     searchCurrent: 'data-plantuml-search-current',
     /** On the node (or its text lines) a `#graph?highlight-node=…` deep link resolved to. */
     focusedNode: 'data-plantuml-focused-node',
+    /** On anchors the plugin synthesized from `[[url]]` links the PlantUML engine dropped. */
+    diagramLink: 'data-plantuml-diagram-link',
 };

package/dist/theme/PlantUmlDiagram/diagramLinks.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Synthesizes the hyperlinks PlantUML's bundled engine drops.
+ *
+ * The engine parses `[[url]]` on components, participants and edges but emits no `<a>`
+ * elements, so authored links are silently lost. What it *does* emit is enough to put them
+ * back: every entity carries its alias in `data-qualified-name` and its source position in
+ * `data-source-line`, and every edge carries `data-source-line` plus its endpoints in
+ * `data-entity-1`/`data-entity-2`. This module extracts the links from the fence source the
+ * plugin already has, correlates each with the rendered element, and wraps that element in a
+ * real `<a>` — clickable, keyboard-focusable, and marked for styling.
+ *
+ * Correlation is a two-layer affair because of `!include`: the engine numbers lines in the
+ * *preprocessed* text, so a stdlib include shifts every `data-source-line` after it and
+ * line-equality silently stops holding. Aliases survive preprocessing untouched, which makes
+ * them the include-proof primary; exact line matching is the fallback that covers unnamed
+ * things (edges, mostly) in include-free sources. Everything here fails safe: a link that
+ * cannot be correlated attaches to nothing.
+ */
+export interface ExtractedLink {
+    /** Zero-based index of the line in the fence source, matching `data-source-line`. */
+    line: number;
+    /** The line's text, used for alias-candidate extraction. */
+    text: string;
+    href: string;
+}
+/**
+ * Schemes a synthesized link may carry. The engine's own output goes through DOMPurify, but
+ * these anchors are built by this module *after* sanitization, so the check lives here.
+ */
+export declare function isSafeLinkHref(href: string): boolean;
+/**
+ * Extracts at most one link per source line.
+ *
+ * One per line is a deliberate ceiling, not laziness: `data-source-line` identifies a line,
+ * not a token, so two links on one line cannot be told apart on the SVG side.
+ */
+export declare function extractSourceLinks(source: string): ExtractedLink[];
+/**
+ * Attaches extracted links to the rendered SVG. Returns how many elements were wrapped.
+ *
+ * Resolution per link, in order:
+ *
+ * 1. **Alias** (include-proof): a declaration line's single candidate that names emitted
+ *    `data-qualified-name` elements wraps all of them. An arrow line whose identifiers name
+ *    exactly two entities wraps the `g.link` connecting them.
+ * 2. **Exact line**: elements whose `data-source-line` equals the author's line index —
+ *    which holds whenever the source was not shifted by preprocessing.
+ */
+export declare function attachDiagramLinks(root: Element, links: ExtractedLink[]): number;
+/** Undoes {@link attachDiagramLinks}: unwraps every synthesized anchor under `root`. */
+export declare function detachDiagramLinks(root: Element): void;

package/dist/theme/PlantUmlDiagram/diagramLinks.js

@@ -0,0 +1,185 @@
+/**
+ * Synthesizes the hyperlinks PlantUML's bundled engine drops.
+ *
+ * The engine parses `[[url]]` on components, participants and edges but emits no `<a>`
+ * elements, so authored links are silently lost. What it *does* emit is enough to put them
+ * back: every entity carries its alias in `data-qualified-name` and its source position in
+ * `data-source-line`, and every edge carries `data-source-line` plus its endpoints in
+ * `data-entity-1`/`data-entity-2`. This module extracts the links from the fence source the
+ * plugin already has, correlates each with the rendered element, and wraps that element in a
+ * real `<a>` — clickable, keyboard-focusable, and marked for styling.
+ *
+ * Correlation is a two-layer affair because of `!include`: the engine numbers lines in the
+ * *preprocessed* text, so a stdlib include shifts every `data-source-line` after it and
+ * line-equality silently stops holding. Aliases survive preprocessing untouched, which makes
+ * them the include-proof primary; exact line matching is the fallback that covers unnamed
+ * things (edges, mostly) in include-free sources. Everything here fails safe: a link that
+ * cannot be correlated attaches to nothing.
+ */
+import { DATA_ATTR } from '../../constants.js';
+/**
+ * Schemes a synthesized link may carry. The engine's own output goes through DOMPurify, but
+ * these anchors are built by this module *after* sanitization, so the check lives here.
+ */
+export function isSafeLinkHref(href) {
+    if (/^(https?:)/i.test(href))
+        return true;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href))
+        return false; // any other explicit scheme
+    return (href.startsWith('/') || href.startsWith('./') || href.startsWith('../') || href.startsWith('#'));
+}
+/** `[[href]]`, `[[href label]]`, `[[href{tooltip}]]` — the href ends at `{`, space, or `]]`. */
+const LINK_PATTERN = /\[\[([^\s{\]]+)[^\]]*\]\]/;
+/** Note lines carry body links the engine renders as styled text; nothing to attach. */
+const NOTE_LINE = /^\s*[rh]?note\b/i;
+/**
+ * Extracts at most one link per source line.
+ *
+ * One per line is a deliberate ceiling, not laziness: `data-source-line` identifies a line,
+ * not a token, so two links on one line cannot be told apart on the SVG side.
+ */
+export function extractSourceLinks(source) {
+    const links = [];
+    const lines = source.split(/\r\n|\r|\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const text = lines[index];
+        if (NOTE_LINE.test(text))
+            continue;
+        const match = LINK_PATTERN.exec(text);
+        if (!match)
+            continue;
+        const href = match[1];
+        if (!isSafeLinkHref(href))
+            continue;
+        links.push({ line: index, text, href });
+    }
+    return links;
+}
+/** `as ALIAS` — the strongest signal a declaration line gives. */
+const AS_ALIAS = /\bas\s+([A-Za-z_][\w]*)/;
+/** C4-style macro: `Container(alias, …)` — the alias is the first argument. */
+const MACRO_ALIAS = /^\s*[A-Za-z_][\w]*\s*\(\s*([A-Za-z_][\w]*)\s*[,)]/;
+/** `component ALIAS [[…]]` — a declaration whose bare name is the alias. */
+const DECL_ALIAS = /^\s*(?:component|actor|participant|database|queue|node|usecase|rectangle|interface|boundary|control|entity|collections|agent|artifact|card|cloud|file|folder|frame|hexagon|package|person|stack|storage|state|object|class|circle|label)\s+([A-Za-z_][\w]*)/i;
+/** Lines with an arrow are relations; their identifiers name the two endpoints. */
+const ARROW = /(-+[->]|\.+[.>]|<[-.]|[-.]{2,})/;
+const IDENTIFIER = /[A-Za-z_][\w]*/g;
+/**
+ * The alias candidates a link line offers, most specific first. `null` means the line's
+ * shape gives no safe candidates and only exact line matching may be used.
+ */
+function aliasCandidates(text) {
+    const as = AS_ALIAS.exec(text);
+    if (as)
+        return [as[1]];
+    const macro = MACRO_ALIAS.exec(text);
+    if (macro)
+        return [macro[1]];
+    const decl = DECL_ALIAS.exec(text);
+    if (decl)
+        return [decl[1]];
+    if (ARROW.test(text)) {
+        // Identifiers before the link only: the label after `:` may contain arbitrary words.
+        const beforeLink = text.slice(0, text.indexOf('[['));
+        return beforeLink.match(IDENTIFIER) ?? [];
+    }
+    return null;
+}
+/**
+ * Participant lifelines run the full height of a sequence diagram; wrapping them would turn
+ * most of the background into a link.
+ */
+function isWrappable(element) {
+    return !(element.getAttribute('class') ?? '').includes('lifeline');
+}
+function wrap(element, href) {
+    if (!isWrappable(element))
+        return false;
+    if (element.closest('a'))
+        return false; // already linked — never nest anchors
+    const parent = element.parentNode;
+    if (!parent)
+        return false;
+    const anchor = element.ownerDocument.createElementNS('http://www.w3.org/2000/svg', 'a');
+    anchor.setAttribute('href', href);
+    anchor.setAttribute(DATA_ATTR.diagramLink, 'true');
+    parent.insertBefore(anchor, element);
+    anchor.appendChild(element);
+    return true;
+}
+/**
+ * Attaches extracted links to the rendered SVG. Returns how many elements were wrapped.
+ *
+ * Resolution per link, in order:
+ *
+ * 1. **Alias** (include-proof): a declaration line's single candidate that names emitted
+ *    `data-qualified-name` elements wraps all of them. An arrow line whose identifiers name
+ *    exactly two entities wraps the `g.link` connecting them.
+ * 2. **Exact line**: elements whose `data-source-line` equals the author's line index —
+ *    which holds whenever the source was not shifted by preprocessing.
+ */
+export function attachDiagramLinks(root, links) {
+    const named = new Map();
+    for (const element of Array.from(root.querySelectorAll('[data-qualified-name]'))) {
+        const name = element.getAttribute('data-qualified-name');
+        const list = named.get(name);
+        if (list)
+            list.push(element);
+        else
+            named.set(name, [element]);
+    }
+    // Entity ids (`ent0001`) are what edges reference in `data-entity-1`/`data-entity-2`.
+    const idToName = new Map();
+    for (const [name, elements] of named) {
+        for (const element of elements) {
+            const id = element.getAttribute('id');
+            if (id)
+                idToName.set(id, name);
+        }
+    }
+    let wrapped = 0;
+    for (const link of links) {
+        const candidates = aliasCandidates(link.text);
+        // 1a. A single alias candidate that exists → wrap every element carrying it.
+        if (candidates !== null) {
+            const matching = candidates.filter((candidate) => named.has(candidate));
+            if (matching.length === 1) {
+                for (const element of named.get(matching[0]) ?? []) {
+                    if (wrap(element, link.href))
+                        wrapped += 1;
+                }
+                continue;
+            }
+            // 1b. Exactly two entities on an arrow line → the edge between them.
+            if (matching.length === 2) {
+                const [a, b] = matching;
+                const edge = Array.from(root.querySelectorAll('g.link')).find((element) => {
+                    const e1 = idToName.get(element.getAttribute('data-entity-1') ?? '');
+                    const e2 = idToName.get(element.getAttribute('data-entity-2') ?? '');
+                    return (e1 === a && e2 === b) || (e1 === b && e2 === a);
+                });
+                if (edge && wrap(edge, link.href)) {
+                    wrapped += 1;
+                    continue;
+                }
+            }
+        }
+        // 2. Exact line match — the fallback for unnamed elements in unshifted sources.
+        for (const element of Array.from(root.querySelectorAll(`[data-source-line="${link.line}"]`))) {
+            if (wrap(element, link.href))
+                wrapped += 1;
+        }
+    }
+    return wrapped;
+}
+/** Undoes {@link attachDiagramLinks}: unwraps every synthesized anchor under `root`. */
+export function detachDiagramLinks(root) {
+    for (const anchor of Array.from(root.querySelectorAll(`a[${DATA_ATTR.diagramLink}]`))) {
+        const parent = anchor.parentNode;
+        if (!parent)
+            continue;
+        while (anchor.firstChild)
+            parent.insertBefore(anchor.firstChild, anchor);
+        anchor.remove();
+    }
+}

package/dist/theme/PlantUmlDiagram/index.js

@@ -12,6 +12,7 @@ import { ChevronDownIcon, ChevronUpIcon, CloseIcon, FitIcon, MaximizeIcon, Minim
 import { parseDiagramHash } from './deeplink.js';
 import Minimap from './Minimap.js';
 import { useDiagramDeeplink } from './useDiagramDeeplink.js';
+import { useDiagramLinks } from './useDiagramLinks.js';
 import { useDiagramSearch } from './useDiagramSearch.js';
 import { useZoomPan } from './useZoomPan.js';
 import styles from './styles.module.css';
@@ -131,6 +132,13 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
         zoom,
         containerRef,
     });
+    useDiagramLinks({
+        ready: state.status === 'ready' && state.svg !== null,
+        svg: state.svg,
+        engine,
+        source,
+        containerRef,
+    });
     // A hash arriving *after* mount must defeat lazy rendering too — a deep link followed
     // from another diagram on the same page may point below the fold. Driven by the router
     // location rather than `hashchange`, which `<Link>` navigations never fire.

package/dist/theme/PlantUmlDiagram/styles.module.css

@@ -196,7 +196,37 @@
  */
 .figure .canvas svg text[data-plantuml-focused-node],
 .figure .canvas svg [data-plantuml-focused-node] text {
-  fill: var(--ifm-color-danger-dark);
+  /*
+   * The theme's success green, not danger red: this highlight persists until the hash
+   * changes, and a standing red reads as an error. Text stays *filled* with an accent
+   * rather than boxed in a light tint because SVG text has no background to tint — and
+   * the variable lets a site pick its own colour without fighting specificity.
+   */
+  fill: var(--plantuml-focus-color, var(--ifm-color-success));
+  text-decoration: underline;
+}
+
+/*
+ * Links inside the picture — Graphviz-native and the anchors synthesized from PlantUML
+ * `[[url]]` links the engine drops. The synthesized ones get the site's link colour so a
+ * linked node is discoverable; Graphviz authors colour their own (`fontcolor=`), so only
+ * the cursor and focus treatment apply there.
+ */
+.canvas svg a {
+  cursor: pointer;
+}
+
+.canvas svg a:focus-visible {
+  outline: 2px solid var(--ifm-color-primary);
+  outline-offset: 1px;
+}
+
+.canvas svg a[data-plantuml-diagram-link] text {
+  fill: var(--ifm-link-color);
+}
+
+.canvas svg a[data-plantuml-diagram-link]:hover text,
+.canvas svg a[data-plantuml-diagram-link]:focus-visible text {
   text-decoration: underline;
 }
 

package/dist/theme/PlantUmlDiagram/useDiagramLinks.d.ts

@@ -0,0 +1,29 @@
+import { type MutableRefObject } from 'react';
+import type { DiagramEngine } from '../../runtime/types.js';
+/**
+ * Author-written links inside one diagram: synthesis and navigation.
+ *
+ * **Synthesis** (PlantUML only): the bundled engine drops `[[url]]` links, so they are
+ * rebuilt from the fence source and attached to the rendered elements — see
+ * `diagramLinks.ts` for the correlation. Graphviz needs none of this; `URL=` already emits
+ * real anchors.
+ *
+ * **Navigation** (both engines): a click on any in-diagram link to a same-site URL goes
+ * through the router instead of a full page load, so a node can link to a diagram on
+ * another page and arrive instantly — with the target page's diagrams reacting to the
+ * hash through the same router-driven deep-link tracking. Site-absolute paths get the
+ * site's `baseUrl`, exactly as markdown links do, so authors write the same `/docs/…`
+ * everywhere. External links and pure `#…` anchors stay native: the browser handles both
+ * correctly on its own, and the router observes hash navigations anyway.
+ */
+export interface UseDiagramLinksParams {
+    /** Whether the diagram is rendered and its SVG is in the DOM. */
+    ready: boolean;
+    /** The rendered SVG string — a dependency, so a re-rendered picture is re-linked. */
+    svg: string | null;
+    engine: DiagramEngine;
+    /** The fence source, exactly as authored — where the links are read from. */
+    source: string;
+    containerRef: MutableRefObject<HTMLElement | null>;
+}
+export declare function useDiagramLinks({ ready, svg, engine, source, containerRef, }: UseDiagramLinksParams): void;

package/dist/theme/PlantUmlDiagram/useDiagramLinks.js

@@ -0,0 +1,62 @@
+import { useEffect } from 'react';
+import { useHistory } from '@docusaurus/router';
+import { useBaseUrlUtils } from '@docusaurus/useBaseUrl';
+import { attachDiagramLinks, detachDiagramLinks, extractSourceLinks } from './diagramLinks.js';
+export function useDiagramLinks({ ready, svg, engine, source, containerRef, }) {
+    const history = useHistory();
+    const { withBaseUrl } = useBaseUrlUtils();
+    // Synthesis. The cleanup unwraps, so a re-rendered or unmounting diagram never leaks
+    // anchors; a replaced SVG re-runs the effect (via `svg`) against the new elements.
+    useEffect(() => {
+        if (!ready || engine !== 'plantuml')
+            return undefined;
+        const canvas = containerRef.current?.querySelector('[role="img"]');
+        if (!canvas)
+            return undefined;
+        const links = extractSourceLinks(source);
+        if (links.length === 0)
+            return undefined;
+        attachDiagramLinks(canvas, links);
+        return () => detachDiagramLinks(canvas);
+    }, [containerRef, engine, ready, source, svg]);
+    // Navigation. One listener on the figure covers synthesized and engine-native anchors
+    // alike. Bubble phase on purpose: the zoom hook suppresses post-drag clicks in the
+    // capture phase, and a suppressed click must not navigate.
+    useEffect(() => {
+        if (!ready)
+            return undefined;
+        const figure = containerRef.current;
+        if (!figure)
+            return undefined;
+        const onClick = (event) => {
+            // Modified clicks are the reader asking the browser for its own behaviour
+            // (new tab, download); never take those over.
+            if (event.defaultPrevented || event.button !== 0)
+                return;
+            if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+                return;
+            const target = event.target instanceof Element ? event.target : null;
+            const anchor = target?.closest('a');
+            if (!anchor || !figure.querySelector('[role="img"]')?.contains(anchor))
+                return;
+            const href = anchor.getAttribute('href') ?? anchor.getAttribute('xlink:href');
+            // Hash-only anchors navigate natively; the router sees hash navigations by itself.
+            if (!href || href.startsWith('#'))
+                return;
+            const resolved = href.startsWith('/') ? withBaseUrl(href) : href;
+            let url;
+            try {
+                url = new URL(resolved, window.location.href);
+            }
+            catch {
+                return;
+            }
+            if (url.origin !== window.location.origin)
+                return;
+            event.preventDefault();
+            history.push(url.pathname + url.search + url.hash);
+        };
+        figure.addEventListener('click', onClick);
+        return () => figure.removeEventListener('click', onClick);
+    }, [containerRef, history, ready, withBaseUrl]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matfsw/docusaurus-plantuml-plugin",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Render PlantUML diagrams in Docusaurus 3 entirely in the browser - no Java, no PlantUML server, no CDN.",
   "keywords": [
     "docusaurus",