README

A custom Neos CMS inspector editor for authoring Mermaid diagrams, plus a Fusion component for rendering them on the frontend.

The editor renders a source <textarea> next to a live Mermaid preview. On Apply it can optionally pre-render the diagram to an SVG and persist it alongside the source, so the frontend can serve the SVG directly without loading Mermaid in the browser.

Screenshots

Empty	Live preview	Syntax error

Features

• React-based inspector editor: source textarea + live, debounced Mermaid preview.
• Inline error display for invalid diagram syntax (never blocks saving).
• Optional server-of-record SVG: the rendered SVG is generated on Apply via a Neos UI save hook and stored next to the source.
• Frontend Fusion component (Wwwision.Neos.MermaidEditor:Diagram) that:
  • serves the stored SVG directly when available, or
  • renders the source client-side (Mermaid loaded on demand), including diagrams injected later via the Neos backend's out-of-band re-rendering.

Requirements

• Neos CMS / Neos UI ^8
• Node.js + npm (only to build the editor plugin, see Development)

Installation

Install the package via composer (from a Neos distribution root):

composer require wwwision/neos-mermaideditor

The package ships a pre-built editor plugin (Resources/Public/MermaidEditor/Plugin.js), so no build step is required for plain usage. If you change the editor sources, rebuild it as described under Development.

Usage

1. Use the editor on a node property

Reference the editor on any string property in a NodeType definition:

'Vendor.Site:MermaidDiagram':
  superTypes:
    'Neos.Neos:Content': true
  properties:
    diagram:
      type: string
      ui:
        label: 'Mermaid Diagram'
        # Show the editor in the creation dialog
        showInCreationDialog: true
        inspector:
          # Re-render the content element in the backend when the value changes
          reloadIfChanged: true
          editor: 'Wwwision.Neos.MermaidEditor/MermaidEditor'
          editorOptions:
            # See "Editor options" below
            renderSvg: true

2. Render the property on the frontend

Pass the decoded property value into the Wwwision.Neos.MermaidEditor:Diagram component:

prototype(Vendor.Site:MermaidDiagram) < prototype(Neos.Neos:ContentComponent) {
    renderer = Wwwision.Neos.MermaidEditor:Diagram {
        # The stored value is always a JSON envelope ({diagram, svg?})
        diagram = ${Json.parse(q(node).property('diagram'))}
    }
}

The component handles three cases:

State	Output
empty / unset	nothing on the frontend; an editing hint in the backend
envelope contains svg	the stored SVG, inline (no client-side Mermaid)
source only	client-side render via Resources/Public/MermaidDiagram.js

Editor options

Option	Type	Default	Description
renderSvg	bool	false	When true, the rendered SVG is generated on Apply and stored alongside the source. The frontend then serves that SVG directly. When false, only the source is stored and the diagram is rendered client-side on the frontend.

Stored data format

The property value is always a JSON envelope:

{ "diagram": "graph TD; A-->B;" }

When renderSvg is enabled, the svg key is added on Apply:

{ "diagram": "graph TD; A-->B;", "svg": "<svg ...>...</svg>" }

If the source is syntactically invalid at Apply time, the SVG is omitted (the envelope stays source-only) so that saving is never blocked.

How it works

Editor (Resources/Private/Scripts/MermaidEditor/src)

• MermaidEditor.js – the React component. It extracts the source from the stored envelope, shows a debounced live preview, and on every change commits JSON.stringify({diagram: source}). When renderSvg is enabled it additionally registers the save hook on the commit.
• manifest.js – registers the editor in the inspector/editors registry and the save hook (Wwwision.Neos.MermaidEditor/RenderSvg) in the inspector/saveHooks registry.
• mermaidRenderer.js – shared Mermaid instance/initialisation, renderSvg() and extractSource() helpers used by both the preview and the save hook.

Save hook

Neos UI save hooks run only when the editor change is applied (not on every keystroke). On Apply the hook renders the source to SVG and returns the {diagram, svg} envelope. Mermaid rendering is asynchronous; the hook returns a Promise, which Neos awaits. Errors are caught and the hook falls back to a source-only envelope — a throwing save hook would abort the entire save.

Frontend rendering

The Wwwision.Neos.MermaidEditor:Diagram Fusion component (Resources/Private/Fusion/Root.fusion) decides per state (see the table above). For the source-only case it emits a <pre class="mermaid" data-mermaid-source="..."> (the source is passed via an attribute so it is reliably HTML-escaped) plus the loader script.

Resources/Public/MermaidDiagram.js:

• loads Mermaid on demand (ES module from the jsDelivr CDN),
• moves each diagram's source from data-mermaid-source into the element text and renders it,
• installs a MutationObserver so diagrams injected later are rendered too. This is required in the Neos backend: reloadIfChanged re-renders the node out-of-band (via AJAX), and the injected markup's own <script> does not execute — the observer (installed on the initial page load) catches the new element and renders it.

Development

The editor plugin is built with esbuild from Resources/Private/Scripts/MermaidEditor into Resources/Public/MermaidEditor.

cd Resources/Private/Scripts/MermaidEditor
npm install
npm run build      # one-off build
npm run watch      # rebuild on change

Outputs:

• Resources/Public/MermaidEditor/Plugin.js
• Resources/Public/MermaidEditor/Plugin.css

After building, you may need to flush Neos caches (and reload the Neos UI) for the changes to appear.

Notes & caveats

• CDN dependency. Client-side rendering (the editor preview always; the frontend only when renderSvg is disabled) loads Mermaid from https://cdn.jsdelivr.net/npm/mermaid@11/.... With renderSvg enabled, the public frontend serves the stored SVG and does not depend on the CDN. To self-host, place a copy of mermaid.esm.min.mjs under Resources/Public/ and adjust the import URLs in Resources/Public/MermaidDiagram.js and the editor sources.
• SVG security. Stored SVG is emitted unescaped on the frontend. Mermaid's securityLevel: 'strict' sanitises at render time, but the SVG is produced during the authoring session.
• Bundle size. The editor plugin bundles Mermaid and is therefore large (~7 MB). This only affects the backend editor, not the public frontend.

Contribution

Contributions in the form of issues or pull requests are highly appreciated

License

See LICENSE