Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
docs(skills): add a skill for developing shared pages
Elian Doran3550f275f3a6
diff --git a/.claude/skills/developing-share-pages/SKILL.md b/.claude/skills/developing-share-pages/SKILL.mdnew file mode 100644index 0000000000..52d35558cc--- /dev/null+++ b/.claude/skills/developing-share-pages/SKILL.md@@ -0,0 +1,167 @@+---+name: developing-share-pages+description: Use when working on Trilium's share functionality — shared pages under `/share/`, the static HTML (share-theme) export, the share theme package (`packages/share-theme`: EJS templates, page model, browser scripts and CSS), core's share renderer (`packages/trilium-core/src/share/content_renderer.ts`, `handlers.ts`, shaca), the per-platform share providers, `~shareTemplate` custom templates, `~shareHtml` snippets, or any `#share*` label. Covers where each piece runs (server, desktop, standalone worker, visitor's browser), the render pipeline from note to page, the page model and its template variables, what custom templates are promised, CSS ordering, how to test each layer (both core runners, happy-dom, node:vm), and the traps already hit on this code.+---++# 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 (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** — `scripts.js` wires the tree, 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.++| Function | Feeds |+| --- | --- |+| `getPageHead` | title, description, no-index, OpenGraph (relative image completed with `#shareOpenGraphURL`), `metaTags` |+| `getHtmlSnippets` | `~shareHtml` per `#shareHtmlLocation` |+| `getSiteLogo` | logo link and size (`#shareLogoWidth/Height` are proportions; drawn 32 px wide) |+| `getShareLink` | **the only** link-target rule: first non-blank of `#shareExternalLink`, `#shareExternal`, else `./shareId` — used by the tree, subpages, index and inline links |+| `getNavigationTree`, `getSiteAncestorIds` | the tree; expansion follows the first parent **inside the site** |+| `getPrevNextLinks` | tree-order previous/next, inside the site; hidden notes get none |+| `getTableOfContents` | nests `PageHeading`s from core's `preparePageContent()` |+| `getChildLinks`, `getContentClasses` | subpage list, `#content` classes |+| `getPageLanguages`, `getLastUpdated` | `<html lang dir>` from the display language, `#content lang dir` from the content language when it differs, the date via `Intl` |++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>`.+- 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.++## Testing++| Layer | How | Command |+| --- | --- | --- |+| page model | fake notes | `pnpm --filter @triliumnext/share-theme test` |+| browser scripts | `// @vitest-environment happy-dom`; set `offsetTop` etc. by hand (no layout) | same |+| inline scripts | render the `.ejs`, run in a `node:vm` context | same |+| core renderer | shaca fixtures (`buildShareNote`), `getContent()` / `renderNoteContent()` | `pnpm --filter server test src/share` **and** `pnpm --filter standalone test src/share` |++- Core specs that render `page.ejs` with hand-built variables (the subpage-list helper in+ `content_renderer.spec.ts`) must be given every new variable, or EJS throws `ReferenceError`.+ Prefer full renders through `renderNoteContent()` for new page-level checks.+- **Prove the red run.** For template or model changes, copy the file to the scratchpad, put the+ `HEAD` version in place (`git show HEAD:<path> > <path>`), run the spec, copy the file back. For+ a pure refactor, render the old and new template with the same values and compare the output.+- node-html-parser elements break Vitest's pretty-printer on failure; assert+ `querySelector(...) === null` as a boolean, or compare mapped attributes.+- Values from a `node:vm` context have another `Object` prototype: use `toEqual`, not+ `toStrictEqual`.+- The share theme's `tsconfig.json` covers specs and browser code alike; a spec needing Node+ types adds `/// <reference types="node" />`.++## Running and seeing a change++- The share theme bundle is served from `packages/share-theme/dist` in development: run+ `pnpm --filter @triliumnext/share-theme build` (or `dev` to watch) after changing its scripts+ or CSS.+- The Node provider **caches each template after the first read**, and core changes need the+ server to restart: restart the dev server after changing a template or the renderer.+- Standalone bundles the templates (`?raw` imports): a **new partial** must be added to+ `TEMPLATES` in `apps/standalone/src/lightweight/share_provider.ts`; the server reads the+ template folder by name and needs nothing.++## Documentation++User-facing share behavior is documented in `docs/User Guide/User Guide/Advanced Usage/Sharing.md`+(feature list, attribute reference, OpenGraph table) and `Sharing/Custom share template.md`+(template variables). Update them in the same commit, then run the `writing-documentation`+skill's `docs.mjs sync` and `check` **from the repository root** — a shell sitting inside+`docs/User Guide` makes the sync fail halfway on Windows and delete hundreds of files.++## Compared with other publishers++Obsidian Publish declares every site `lang="en"` (even its Chinese and Japanese help sites) and+has no language setting. Quartz takes `lang` from a site locale or a note's frontmatter and formats+dates with that locale. Trilium marks the page with the display language and the content with the+note's content language separately, so the theme's own texts are not mislabeled.