Rendered Fences Design

Shipped in 2.5.0 (2026-10-25). The repo spec is docs/superpowers/specs/2026-10-24-rendered-fences-design.md; this page is the as-built summary.

Second renderer: server-rendered PlantUML for UML class, activity and other @startuml diagrams shipped in 2.5.1 — see PlantUmlFencesDesign.

Why Mermaid fences never rendered before 2.5.0

Before 2.5.0 the production corpus held 63 ```mermaid fences on 43 pages, and none of them drew. The server's Flexmark setup turned GitLab's Mermaid rendering off, and the frontend had no diagram library, so every diagram showed as a plain code block. The content agent requires a diagram on every non-hub page, so the count kept growing.

The goal was to draw those diagrams for human readers, keep the source text for every machine consumer, and build the mechanism as a general hook: a rendered fence is any fenced block whose language a registered renderer claims. Mermaid was the first renderer and PlantUML the second; Vega-Lite is a possible next one.

How a rendered fence flows from markdown to a drawing

flowchart LR
  MD[Page markdown] --> Flex[Flexmark node renderer]
  Flex --> Policy{Server safety policy}
  Policy -->|allowed| Env[figure.wk-fence envelope with source]
  Policy -->|refused| Ref[envelope plus refusal reason]
  Env --> Browser{Browser policy and Mermaid}
  Browser -->|ok| SVG[Drawn SVG plus Show source]
  Browser -->|error| Err[Source plus parse error]
  MD --> Scan[RenderedFenceScanner]
  Scan --> Refs[ReferenceManager links]
  click Refs "/wiki/PageGraphVsKnowledgeGraph"

The source text always reaches the served HTML (SSR /wiki/{slug} and contentHtml). ?format=md, the for-agent projection, chunking, embeddings and export all carry raw markdown and are unchanged.

The info-string grammar and the example modifier

• The language is the first whitespace-delimited word of the info string, lowercased. Any further words are modifiers.
• The word example means "show this as ordinary code". It is handled once, for every rendered-fence language, so no renderer implements it.
• Unknown modifiers are ignored, which leaves room for future ones.

flowchart LR
  Draft --> Review
  click Review "/wiki/EditPageHelp"

The block above is written with the example modifier, so it shows its syntax instead of drawing.

The envelope shape and the two renderer kinds

Every rendered fence is emitted in one fixed shape: <figure class="wk-fence" data-fence data-fence-kind> wrapping <pre class="wk-fence-source"><code class="language-mermaid">, with the source HTML-escaped.

• Browser renderers (Mermaid) get only the source, and the browser draws it.
• Server renderers (PlantUML, since 2.5.1) emit a signed placeholder at render time; the drawing is spliced in once, at the outermost render, so page caches never hold drawings. See PlantUmlFencesDesign.

To add a renderer, read the RenderedFenceRenderer Javadoc in com.wikantik.markdown.extensions.fences and the header of wikantik-frontend/src/utils/fences/registry.js. Both are written as the how-to guide.

Fail-closed Mermaid safety policy, enforced twice

The policy refuses whole categories rather than mirroring Mermaid's lexers. Four review rounds showed that a deny-list of specific patterns never converges. A Mermaid fence is refused if it contains any of these:

• a %%{ … }%% directive;
• a --- front-matter block;
• javascript: anywhere;
• a click line that calls a function;
• a link target that is not http(s) or site-relative;
• a colon in a click tooltip.

HTML entities are decoded before link targets are checked, and the checks also run on statement fragments split at ;.

The same rules exist in Java (MermaidStatementPolicy, MermaidUrlRules, MermaidTextRules) and in JavaScript (mermaidPolicy.js), because the editor previews never call the server. One shared fixture, wikantik-frontend/src/utils/__fixtures__/renderedFences.json, drives both test suites, so the two cannot drift. A refused fence shows its source and the reason, never a blank space.

As a second layer, Mermaid runs at securityLevel: antiscript. Its secure key list covers dompurifyConfig and htmlLabels, and a hardened dompurifyConfig strips forms, inputs and inline styles from labels. In review, labels were found able to carry working off-site forms, which this closes.

Diagram links in backlinks, the Page Graph and broken links

A line click Node "/wiki/PageName" makes the node a link, and the page link counts as a real reference. RenderedFenceScanner is a raw-text scanner, so no Flexmark parse is needed. It finds rendered fences, including ~~~, indented, list-nested and blockquote-nested ones, skips example fences, and feeds each renderer's link extractor into DefaultReferenceManager.scanWikiLinks. Bumping the reference manager's cache version made 2.5.0's first startup rescan every page, which took 4.5 seconds on prod.

External http(s) targets are clickable but not tracked. Renaming a page does not yet rewrite diagram links. The rename would have to touch only the renderer's own link syntax, only inside rendered fences and never in example fences.

What readers and editors see

• Reader view: the drawn SVG, fit to the column, with an Expand view when it is scaled down. A Show source toggle with a copy button keeps the source in the DOM for text-reading tools.
• Editor: diagrams draw identically in the preview pane, the in-editor live preview and inside ![[embeds]].
• Theme switch: diagrams redraw on light/dark changes.
• Download cost: Mermaid loads lazily as its own chunk, only on pages with diagrams.
• Layout engine: dagre, not Mermaid 12's default ELK, which would add about 456 kB gzip.

Corpus checking with check-mermaid.mjs

node wikantik-frontend/scripts/check-mermaid.mjs [--json] <files|dir|-> parses every diagram it finds. It exits 0 when all diagrams parse, 1 when some are broken, and 2 when the checker itself fails. The content agent's linter calls it and reports a broken diagram as a required fix. Before the release, the three prod diagrams that did not parse (RecommendationSystems, SimpleAgilityAttributionRFC, SimpleAgilityCommerceDataFlow) were repaired, and all 63 prod diagrams draw. PlantUML has the matching bin/check-plantuml.sh.

Deliberately out of scope

• Moving ```math onto the hook.
• A production Vega-Lite renderer.
• Plugin syntax for diagrams.
• Rewriting diagram links on rename.

See WikantikDevelopmentHub for the rest of the platform designs.