Developing Share Pages

Developing shared pages

A shared note is rendered on the backend into a complete HTML page by core, using the share theme's EJS templates, and then enhanced in the visitor's browser by the share theme's script bundle. The same renderer produces the static HTML export, with every page written to a ZIP.

Where the code lives

packages/trilium-core/src/share/        backend, runs in server, desktop and the standalone worker
  route_paths.ts       SHARE_ROUTE_PATHS (import-free, so a platform can register routes cheaply)
  handlers.ts          transport-neutral handlers: credentials, protected notes, raw, images, search
  content_renderer.ts  note → content HTML (getContent), page render (renderNoteContent,
                       renderNoteForExport), preparePageContent, highlighting
  shaca/               share cache: SNote/SBranch/SAttribute/SAttachment over a read-only SQL view
  share_provider.ts    ShareProvider interface: sql, readTemplate, isScriptingEnabled, isReady
apps/server/src/share/                  Express adapter (routes.ts) + Node provider (share_provider.ts)
apps/standalone/src/lightweight/        browser provider (share_provider.ts: templates bundled ?raw)
                                        and route adapter (browser_routes.ts)
packages/trilium-core/src/services/export/zip/share_theme.ts   static export (renderNoteForExport)
packages/share-theme/
  src/model/page.ts    the page model: pure functions from notes to template values
  src/templates/       page.ejs + partials (boot_script, tree_item, toc_item, prev_next, 404)
  src/index.ts         browser entry; imports CSS in cascade order, calls each setup*()
  src/page/            page chrome: one script next to its CSS (layout, header, navigation,
                       search, toc, theme_switch, footer)
  src/content/         content enhancements (math, mermaid) and content CSS
  scripts/build.ts     esbuild → dist/scripts.js + dist/scripts.css, and dist/tree.js on its own
                       (no code splitting, so it loads as one file) (run by tsx)

packages/share-theme/package.json exports ./templates/* and ./model/* from source (core imports the model as @triliumnext/share-theme/model/page); everything else resolves to dist/.

The render pipeline

1. Route — handlers.ts resolves the note through shaca, checks shareCredentials, rejects protected notes, and calls renderNoteContent(note, canAccessEmbed). A page route first awaits ensureShareHighlighting() (the renderer is synchronous; language registration is not).
2. Content — getContent(note, options) renders by note type into { header, content, isEmpty }. Text goes through renderText() (node-html-parser): include-note embeds via the commons resolver (resolveContentEmbed), link previews via commons markup, reference links, inline links via getShareLink(), syntax highlighting bounded by shouldSyntaxHighlight().
3. Template values — renderNoteContentInternal() builds the variables: the legacy ones (note, content, subRoot, cssToLoad, jsToLoad, t, utils, ancestors, …) plus the page model's (head, snippets, logo, prevNext, navigation, childLinks, language, lastUpdated, contentClasses).
4. Template — a ~shareTemplate (only when backend scripting is enabled) gets those values with the content as it is. The default page.ejs additionally gets the output of preparePageContent(): content with heading anchors and image alt/loading, headings and toc.
5. Browser — tree.js, the first entry of jsToLoad and the only blocking="render" one, restores the tree's expansion, scroll position and clicked clone before the first paint. scripts.js then wires the expand buttons, search, ToC scroll tracking, theme switch, footer date, math, Mermaid, link previews and tabs. boot_script.ejs runs inline in <head> before the first paint (theme class, collapsed panes, window.glob).

The static export calls renderNoteForExport() with isStatic: true, which also expands embeds at every depth and drops the login link and the last-updated date.

The page model (packages/share-theme/src/model/page.ts)

Everything a template would otherwise compute lives here, as pure functions over ShareNote, the structural subset of a note that both SNote and BNote satisfy (pnpm typecheck verifies this; extend the interface rather than importing core types). Its spec runs on plain fake notes (fakeNote() / addChild() in page.spec.ts) — no shaca, no database.

Rules:

• Templates only print. A condition belongs in a template only if it tests a value the model already produced (navigation.length, childLinks.length). Anything that walks notes, reads labels or transforms HTML goes into the model (or into core when it changes content).
• Content transforms belong to core, in the parse renderText()/preparePageContent() already does — never a regex over HTML in a template.
• A clone's "parent" is always the first parent inside the site (getSitePosition()), never getParentNotes()[0].

What custom templates are promised

~shareTemplate notes are copies of an earlier page.ejs, documented on the Custom share template page of the User Guide. So:

• Never remove or rename a template variable, even an unused one (header is always ""). Add new ones and list them in that page's table.
• Custom templates receive content without the anchors and image attributes preparePageContent() adds: copies of the old template add their own, and doubling them shows twice. headings/toc are passed to the default template only.
• Partials of a custom template resolve from its child notes, not from the theme's templates.

Browser side

• Every module imports its own CSS; index.ts imports in cascade order (a module's CSS lands where it is first imported). Moving an import moves CSS; compare the bundle's declarations when reordering.
• No inline scripts besides boot_script.ejs. Top-level const/let in a classic inline script is a global binding shared with ~shareHtml snippets — keep everything inside the IIFE. boot_script.spec.ts enforces both and that page.ejs has no <script>.
• Code that must run before the first paint and needs the DOM goes in tree.ts's bundle, which is render-blocking; keep it small, since every page waits for it. Everything else stays in scripts.js, and ~shareJs scripts never block.
• Anything needed before the first paint is driven from the root class the boot script sets (theme-dark/theme-light, left-pane-collapsed) — the theme switch is styled from it, not from :checked, so it needs no script to look right.
• Look elements up by ID with getElementById, not querySelector("#" + slug) (a slug may start with a digit).
• Code shared with the app comes from commons or ckeditor5 by subpath (@triliumnext/commons/src/lib/…, e.g. enhanceLinkPreviews, getMermaidConfig, applyTabs); shared content CSS comes from packages/ckeditor5/src/theme/.
• Mermaid loads the client's share_mermaid entry through the client/share_mermaid.json manifest, so diagrams match the app; it redraws on theme change.