Render Note Execution#

A render note (type render) displays output generated by one or more linked script notes, connected via the renderNote relation. Unlike the standard text-rendering pipeline (CKEditor post-processing, reference-link resolution, mermaid, etc.), render notes bypass content parsing entirely: the server compiles a bundle of script + HTML, the client injects the HTML directly into the DOM, and executes the script asynchronously.

The full pipeline spans three layers:

Render.tsx widget
  └─ render.tsx service → POST script/bundle/:noteId → server getScriptBundleForFrontend
       ├─ append bundle.html to DOM
       └─ executeBundleWithoutErrorHandling (async, fire-and-forget)
            └─ eval(bundle.script) inside ScriptContext
                 └─ [optional] renderIfJsx → Preact component mount

Entry Point: Render Widget#

Render.tsx is the Preact type widget for render notes. It dispatches to one of three sub-components based on the note's renderNote/disabled:renderNote relations 1:

• RenderContent — note has a renderNote relation; performs the actual render.
• SetupRenderContent — no relation yet; shows a setup UI to pick or create a script note.
• DisabledRender — relation is explicitly disabled; shows a re-enable button.

RenderContent holds a contentRef div and triggers a refresh() via useEffect whenever the note changes. It also re-renders in response to Trilium events: renderActiveNote (keyboard shortcut), refreshData (floating buttons), and entitiesReloaded (attribute changes on the renderNote relation) 2.

The widget is registered as the type widget for render notes in note_types.tsx 3.

Bundle Fetch#

render() in render.tsx drives the fetch loop:

1. Collects all renderNote relation values (note IDs) from the note 4.
2. Clears the container and hides it if no render note IDs exist 5.
3. For each render note ID, POSTs to script/bundle/:renderNoteId via server.postWithSilentInternalServerError<Bundle>() 6. A missing bundle (e.g., a protected note without an active session) throws immediately with a descriptive message 7.

The server-side handler getBundle in script.ts 8 calls getScriptBundleForFrontend() 9, which returns a Bundle with:

JSX notes are transpiled server-side (Sucrase) before inclusion. The note / allNotes objects are stripped before transmission; the frontend uses its own FNote instances instead 10.

DOM Injection#

For each bundle, render() creates a fresh <div> container, appends it to the widget element, then injects bundle.html directly — no sanitization, as the HTML is authored by the user 11. Multiple renderNote relations produce multiple sibling containers in the order the relations are defined.

Asynchronous Script Execution#

Script execution is deliberately fire-and-forget — the promise from executeBundleWithoutErrorHandling() is not awaited so scripts cannot block the Trilium UI 12. In bundle.ts:

1. Builds a ScriptContext object containing modules, notes (keyed by ID), apis (a FrontendScriptApi instance per note), and a require() resolver for loading child notes as modules.
2. Runs eval() of the script as an async IIFE with the context bound as this 13.

The $container jQuery element is passed through to the context so scripts can write into their own DOM subtree.

JSX Component Path#

After execution, if bundle.html is empty (no HTML child notes), renderIfJsx() runs:

1. Confirms the root note MIME is text/jsx; silently returns otherwise 14.
2. Confirms the execution result is a function (a Preact component) 15.
3. Wraps the component in a UserErrorBoundary and calls renderReactWidgetAtElement() to mount it at the container element 16.

Error Handling#

• Execution errors are caught by the .catch() in render() and forwarded to onError, which RenderContent uses to set an error state — displaying a RenderErrorCard in place of the content 17.
• JSON-shaped error strings from the server are parsed before forwarding 18.
• When render notes are displayed via getRenderedContent() in content_renderer.ts (e.g., in previews), showRenderError() lazily imports and mounts RenderErrorCard as a fallback.

Key Source Files#