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
/**
* The values `page.ejs` prints, worked out from the note before the template runs. Custom
* `~shareTemplate` templates receive them too.
*/
import {
isRightToLeftLanguage, resolveContentLanguage, toLanguageTag
} from "@triliumnext/commons/src/lib/i18n.js";
import { isFullWidthNoteType } from "@triliumnext/commons/src/lib/notes.js";
/** The parts of a note the page model reads; core's `SNote` and `BNote` both provide them. */
export interface ShareNote {
noteId: string;
shareId: string;
title: string;
/** When the note was last changed, as Trilium stores it (`2026-10-09 12:00:00.000Z`). */
utcDateModified?: string;
getLabelValue(name: string): string | null | undefined;
hasLabel(name: string): boolean;
/** Whether the label is set to anything but `false`. */
isLabelTruthy(name: string): boolean;
getRelationValue(name: string): string | null | undefined;
hasRelation(name: string): boolean;
getRelations(name: string): { targetNote?: ShareNote | null }[];
getContent(): string | Uint8Array | null | undefined;
getParentNotes(): ShareNote[];
getVisibleChildNotes(): ShareNote[];
type: string;
mime: string;
/** The icon's CSS classes, among the icon packs whose prefixes are given. */
getIcon(iconPackPrefixes?: string[]): string;
}
/** Where a link to a note goes: its page, or the address of its external link. */
export interface ShareLink {
href: string;
/** Whether the link goes to `#shareExternalLink` or `#shareExternal`. */
isExternal: boolean;
}
/** An entry of the navigation tree, with the entries below it. */
export interface NavigationItem extends ShareLink {
noteId: string;
title: string;
type: string;
icon: string;
/** Whether the entry is the page being shown. */
isActive: boolean;
/** Whether the entry is the page being shown or one of its ancestors. */
isExpanded: boolean;
/** How many children the note keeps out of the tree with `#subtreeHidden`, or 0. */
hiddenChildCount: number;
children: NavigationItem[];
}
/** A link to another page of the site. */
export interface PageLink {
title: string;
href: string;
}
/** What goes into the `<head>` of a shared page, besides the stylesheets and scripts. */
export interface PageHead {
/** The note's title, followed by the site's unless the note is the site's root. */
title: string;
/** `#shareDescription`; this and the other values are `null` when their label is blank. */
description: string | null;
/** Whether search engines are asked not to index the page (`#shareDisallowRobotIndexing`). */
noIndex: boolean;
openGraph: {
url: string | null;
domain: string | null;
/** Absolute when `url` is set and is a valid address, relative to the page otherwise. */
image: string | null;
color: string | null;
/** The kind of Twitter card: a large picture when there is an image. */
card: "summary_large_image" | "summary";
};
/** The description, OpenGraph and Twitter `<meta>` tags of the values that are set. */
metaTags: MetaTag[];
}
/** A `<meta>` tag, such as `<meta property="og:title" content="…">`. */
export interface MetaTag {
attribute: "name" | "property";
key: string;
content: string;
}
/** The site logo in the page header. */
export interface SiteLogo {
/** `#shareRootLink` when set, otherwise the site's root page. */
href: string;
/** The `~shareLogo` image, or `null` to show {@link SiteLogo.icon} instead. */
image: string | null;
/** The icon classes of the site root's note icon. */
icon: string;
/** The size to draw {@link SiteLogo.image} at. */
width: number;
height: number;
}
/** What {@link getSiteLogo} needs besides the site root. */
export interface SiteLogoOptions {
/** Makes `#shareRootLink` safe to use as a link. */
sanitizeUrl: (url: string) => string;
/** The URL of the `~shareLogo` image, if any. */
image: string | null;
iconPackPrefixes?: string[];
}
/** A heading of the page's content, as core's `preparePageContent()` finds it. */
export interface PageHeading {
/** 1 for `<h1>`, up to 6 for `<h6>`. */
level: number;
/** The heading's plain text. */
text: string;
/** The heading's text with its inline formatting, such as `<code>`, as safe HTML. */
html: string;
/** The ID of the heading's anchor, unique on the page. */
slug: string;
/** The link to the heading: `#` and `slug`, URL-encoded. */
href: string;
}
/** An entry of the table of contents, with the headings it contains. */
export interface TableOfContentsEntry extends PageHeading {
children: TableOfContentsEntry[];
}
/** Where an HTML snippet can go, as `#shareHtmlLocation` names it. */
export type HtmlSnippetLocation =
`${"head" | "body" | "content"}:${"start" | "end"}`;
/**
* Returns the `<head>` values of the page of `note`, whose site starts at `siteRoot`. The
* OpenGraph values come from the site root, so that every page of a site shares them. Sites that
* show a link preview load the image from their own servers, so a relative image address is made
* absolute against `#shareOpenGraphURL`, the only public address of the site Trilium knows.
*/
export function getPageHead(note: ShareNote, siteRoot: ShareNote): PageHead {
const title = note.noteId === siteRoot.noteId
? note.title
: `${note.title} - ${siteRoot.title}`;
const url = readLabel(siteRoot, "shareOpenGraphURL");
const image = siteRoot.hasRelation("shareOpenGraphImage")
? `api/images/${siteRoot.getRelationValue("shareOpenGraphImage")}/image.png`
: readLabel(siteRoot, "shareOpenGraphImage");
const description = readLabel(note, "shareDescription");
const openGraph: PageHead["openGraph"] = {
url,
domain: readLabel(siteRoot, "shareOpenGraphDomain"),
image: image && url ? toAbsoluteUrl(image, url) : image,
color: readLabel(siteRoot, "shareOpenGraphColor"),
card: image ? "summary_large_image" : "summary"
};
return {
title,
description,
noIndex: note.hasLabel("shareDisallowRobotIndexing"),
openGraph,
metaTags: getMetaTags(title, description, openGraph)
};
}
function getMetaTags(title: string, description: string | null, openGraph: PageHead["openGraph"]) {
const tags: [ MetaTag["attribute"], string, string | null ][] = [
[ "name", "description", description ],
[ "property", "og:type", "website" ],
[ "property", "og:title", title ],
[ "property", "og:description", description ],
[ "property", "og:url", openGraph.url ],
[ "property", "og:image", openGraph.image ],
[ "name", "twitter:card", openGraph.card ],
[ "name", "twitter:title", title ],
[ "name", "twitter:description", description ],
[ "property", "twitter:domain", openGraph.domain ],
[ "property", "twitter:url", openGraph.url ],
[ "name", "twitter:image", openGraph.image ],
[ "name", "theme-color", openGraph.color ]
];
return tags.flatMap(([ attribute, key, content ]): MetaTag[] =>
(content ? [ { attribute, key, content } ] : []));
}
/** A language and its writing direction, for the `lang` and `dir` attributes of an element. */
export interface PageLanguage {
lang: string;
dir: "ltr" | "rtl";
}
/** The languages Trilium is set to, as the `locale` and `defaultContentLanguage` options give them. */
export interface LanguageSettings {
displayLanguage: string;
defaultContentLanguage?: string | null;
}
/**
* Returns the language of the page, which is the display language its own texts are translated
* to, and the language of the note's content when it is another: the note's `#language`,
* otherwise the default content language.
*/
export function getPageLanguages(note: ShareNote, settings: LanguageSettings) {
const page = toPageLanguage(settings.displayLanguage);
const content = toPageLanguage(resolveContentLanguage(note.getLabelValue("language"),
settings.defaultContentLanguage, settings.displayLanguage) ?? settings.displayLanguage);
return {
page,
content: content.lang === page.lang && content.dir === page.dir ? null : content
};
}
function toPageLanguage(localeId: string): PageLanguage {
return { lang: toLanguageTag(localeId), dir: isRightToLeftLanguage(localeId) ? "rtl" : "ltr" };
}
/**
* Returns when `note` was last changed, as an ISO date for a `<time>` element and as a date
* written out in the display language, or `null` when the note has no valid date.
*/
export function getLastUpdated(note: ShareNote, displayLanguage: string) {
const date = new Date(note.utcDateModified ?? Number.NaN);
if (Number.isNaN(date.getTime())) {
return null;
}
return {
iso: date.toISOString(),
text: new Intl.DateTimeFormat(toLanguageTag(displayLanguage), { dateStyle: "long" }).format(date)
};
}
/** Returns the trimmed value of the label, or `null` when it is missing or blank. */
function readLabel(note: ShareNote, name: string) {
return note.getLabelValue(name)?.trim() || null;
}
const CHILD_LIST_NOTE_TYPES = [ "book", "text", "code" ];
/** The most children of a child its card lists, as many as the app's card does. */
const CHILD_PREVIEW_LENGTH = 10;
/** Resolves `address` against `base` unless it is already absolute or `base` is not a URL. */
function toAbsoluteUrl(address: string, base: string) {
if (URL.canParse(address) || !URL.canParse(base)) {
return address;
}
return new URL(address, base).href;
}
/**
* Returns the HTML of the `~shareHtml` snippets of `note`, joined per location. A snippet goes to
* `#shareHtmlLocation`, `content:end` without one, and to the end of a location named without a
* position. Every location is present, empty when no snippet goes there.
*/
export function getHtmlSnippets(note: ShareNote): Record<HtmlSnippetLocation, string> {
const snippets: Record<string, string[]> = {
"head:start": [],
"head:end": [],
"body:start": [],
"body:end": [],
"content:start": [],
"content:end": []
};
for (const { targetNote } of note.getRelations("shareHtml")) {
if (!targetNote) {
continue;
}
let location = targetNote.getLabelValue("shareHtmlLocation") || "content:end";
if (!location.includes(":")) {
location = `${location}:end`;
}
const content = targetNote.getContent();
(snippets[location] ??= []).push(typeof content === "string" ? content : "");
}
return Object.fromEntries(Object.entries(snippets)
.map(([ location, contents ]) => [ location, contents.join("\n") ])
) as Record<HtmlSnippetLocation, string>;
}
/** The width the header draws the site logo at, in pixels. */
const LOGO_WIDTH = 32;
/**
* Returns the site logo of the site starting at `siteRoot`: the `~shareLogo` image when there is
* one, otherwise the site root's note icon. `#shareLogoWidth` and `#shareLogoHeight` give the
* image's proportions; a label that is not a positive number falls back to 53 by 40.
*/
export function getSiteLogo(siteRoot: ShareNote, options: SiteLogoOptions): SiteLogo {
const width = readPositiveNumber(siteRoot.getLabelValue("shareLogoWidth")) ?? 53;
const height = readPositiveNumber(siteRoot.getLabelValue("shareLogoHeight")) ?? 40;
const rootLink = siteRoot.getLabelValue("shareRootLink");
return {
href: rootLink ? options.sanitizeUrl(rootLink) : `./${siteRoot.shareId}`,
image: options.image,
icon: siteRoot.getIcon(options.iconPackPrefixes),
width: LOGO_WIDTH,
height: Math.round(LOGO_WIDTH * height / width)
};
}
function readPositiveNumber(value: string | null | undefined) {
const number = Number(value);
return value && number > 0 ? number : undefined;
}
/**
* Returns the table of contents of a page with `headings`. Each heading goes under the closest
* heading before it of a higher level, such as an `<h3>` under the `<h2>` before it, and at the top
* when there is none.
*/
export function getTableOfContents(headings: PageHeading[]): TableOfContentsEntry[] {
const toc: TableOfContentsEntry[] = [];
const open: TableOfContentsEntry[] = [];
for (const heading of headings) {
const entry = { ...heading, children: [] };
while (open.length && open[open.length - 1].level >= heading.level) {
open.pop();
}
(open.at(-1)?.children ?? toc).push(entry);
open.push(entry);
}
return toc;
}
/**
* Returns where a link to `note` goes: the first of `#shareExternalLink` and `#shareExternal` that
* is not blank, made safe by `sanitizeUrl`, otherwise the note's page.
*/
export function getShareLink(note: ShareNote, sanitizeUrl: (url: string) => string): ShareLink {
const externalLink = note.getLabelValue("shareExternalLink")?.trim()
|| note.getLabelValue("shareExternal")?.trim();
return externalLink
? { href: sanitizeUrl(externalLink), isExternal: true }
: { href: `./${note.shareId}`, isExternal: false };
}
/**
* Returns the classes of the content element: the note's type, `ck-content` for content the text
* editor's styles apply to (text notes and Markdown code notes), `full-content-width` for a note
* with `#fullContentWidth`, of a type the app always shows at full width or taking the page's full
* height, `full-height` and `app-view` for content that takes the page's full height and for an
* app view, and `no-content` when empty. A Markdown note reads as text, so its type does not make it
* full width.
*/
export function getContentClasses(
note: ShareNote,
isEmpty = false,
{ isAppView = false, isFullHeight = false }: { isAppView?: boolean; isFullHeight?: boolean } = {}
) {
const isEditorContent = note.type === "text"
|| (note.type === "code" && note.mime === "text/x-markdown");
const isFullWidth = (!isEditorContent && isFullWidthNoteType(note.type, note.mime))
|| note.isLabelTruthy("fullContentWidth") || isFullHeight;
return [
`type-${note.type}`,
isEditorContent && "ck-content",
isFullWidth && "full-content-width",
isFullHeight && "full-height",
isAppView && "app-view",
isEmpty && "no-content"
].filter(Boolean).join(" ");
}
/** A child of a page, as its list of subpages shows it. */
export interface ChildLink extends ShareLink {
title: string;
type: string;
/** The icon's CSS classes. */
icon: string;
/** `#shareDescription`, else the start of the child's text, or `null`. */
excerpt: string | null;
/**
* The first visible children of the child, which the app's card shows in place of a preview
* when the child has none; empty when it has an excerpt.
*/
children: ChildLinkChild[];
}
/** A child of a child of a page, as its card lists it. */
export interface ChildLinkChild extends ShareLink {
title: string;
/** The icon's CSS classes. */
icon: string;
}
/** What {@link getChildLinks} needs besides the note. */
export interface ChildLinksOptions {
sanitizeUrl: (url: string) => string;
/** The prefixes of the icon packs available to the page, for the children's icons. */
iconPackPrefixes?: string[];
/**
* The plain text a child's excerpt starts from, or `null` for none, such as a child the
* visitor is not allowed to read. Without it, only `#shareDescription` describes a child.
*/
getText?: (note: ShareNote) => string | null;
/**
* Whether the visitor is allowed to read a child. A child they are not allowed to read has no
* excerpt, not even its `#shareDescription`.
*/
canAccess?: (note: ShareNote) => boolean;
}
/**
* Returns the links to the visible children of `note`, for its list of subpages. As in the app,
* only a collection, a text note and a code note list their children, and `#hideChildrenOverview`
* hides the list.
*/
export function getChildLinks(note: ShareNote, options: ChildLinksOptions): ChildLink[] {
if (!CHILD_LIST_NOTE_TYPES.includes(note.type) || note.isLabelTruthy("hideChildrenOverview")) {
return [];
}
return note.getVisibleChildNotes().map((child) => {
const excerpt = options.canAccess?.(child) === false ? null
: readLabel(child, "shareDescription") ?? toExcerpt(options.getText?.(child) ?? "");
const children = excerpt ? [] : child.getVisibleChildNotes().slice(0, CHILD_PREVIEW_LENGTH);
return {
...getShareLink(child, options.sanitizeUrl),
title: child.title,
type: child.type,
icon: child.getIcon(options.iconPackPrefixes),
excerpt,
children: children.map((grandchild) => ({
...getShareLink(grandchild, options.sanitizeUrl),
title: grandchild.title,
icon: grandchild.getIcon(options.iconPackPrefixes)
}))
};
});
}
/** The most characters of a child's text its excerpt shows, about what fills its card's preview. */
const EXCERPT_LENGTH = 500;
/**
* Shortens `text`, whose paragraphs are separated by blank lines, to an excerpt of at most
* {@link EXCERPT_LENGTH} characters with a line break between paragraphs: whole sentences or
* paragraphs when they fill at least a third of it, else whole words followed by an ellipsis.
*/
function toExcerpt(text: string) {
const plain = text.split(/\n\s*\n/)
.map((paragraph) => paragraph.replace(/\s+/g, " ").trim())
.filter(Boolean)
.join("\n");
if (plain.length <= EXCERPT_LENGTH) {
return plain || null;
}
const head = plain.slice(0, EXCERPT_LENGTH);
const end = [ ...head.matchAll(/[.!?](?=\s)|[^\n](?=\n)/g) ].at(-1);
if (end && end.index >= EXCERPT_LENGTH / 3) {
return head.slice(0, end.index + 1);
}
const wordEnd = head.lastIndexOf(" ");
return `${wordEnd > 0 ? head.slice(0, wordEnd) : head}…`;
}
/**
* Returns how the list of subpages is laid out: a grid, unless the note is a collection whose view
* type is `list`. The caller resolves the view type, which can come from a template outside the share.
*/
export function getChildLinksLayout(note: ShareNote, viewType: string | null): "grid" | "list" {
return note.type === "book" && viewType === "list" ? "list" : "grid";
}
/** What {@link getNavigationTree} needs besides the notes. */
export interface NavigationTreeOptions {
sanitizeUrl: (url: string) => string;
/** The prefixes of the icon packs available to the page, for the notes' icons. */
iconPackPrefixes?: string[];
/** Whether the note keeps its children out of the tree; none does by default. */
isSubtreeHidden?: (note: ShareNote) => boolean;
}
/**
* Returns the navigation tree of the site starting at `siteRoot`: its visible pages, below one
* another as in the note tree. The entries of `activeNote` and of the notes in `ancestorIds` are
* expanded. Of a cloned `activeNote`, only the entry below exactly the notes in `ancestorIds` is
* the active one; their order and whether they include `siteRoot` do not matter.
*
* A note whose subtree is hidden lists none of its children, except the one leading to
* `activeNote`, so the page being shown keeps its place in the tree.
*/
export function getNavigationTree(
siteRoot: ShareNote, activeNote: ShareNote, ancestorIds: string[], options: NavigationTreeOptions
): NavigationItem[] {
const expandedIds = new Set([ activeNote.noteId, ...ancestorIds ]);
const activeAncestorIds = new Set(ancestorIds.filter((noteId) => noteId !== siteRoot.noteId));
const isActive = (note: ShareNote, path: string[]) => note.noteId === activeNote.noteId
&& path.length === activeAncestorIds.size
&& path.every((noteId) => activeAncestorIds.has(noteId));
const toItem = (note: ShareNote, path: string[]): NavigationItem => {
const children = note.getVisibleChildNotes();
const isHidden = children.length > 0 && !!options.isSubtreeHidden?.(note);
return {
...getShareLink(note, options.sanitizeUrl),
noteId: note.noteId,
title: note.title,
type: note.type,
icon: note.getIcon(options.iconPackPrefixes),
isActive: isActive(note, path),
isExpanded: expandedIds.has(note.noteId),
hiddenChildCount: isHidden ? children.length : 0,
children: (isHidden ? children.filter((child) => expandedIds.has(child.noteId)) : children)
.map((child) => toItem(child, [ ...path, note.noteId ]))
};
};
return siteRoot.getVisibleChildNotes().map((note) => toItem(note, []));
}
/**
* Returns whether a navigation tree has an entry for the page being shown, which the site root
* and a note hidden from the tree do not.
*/
export function hasActiveItem(items: NavigationItem[]): boolean {
return items.some((item) => item.isActive || hasActiveItem(item.children));
}
/**
* Returns the IDs of the notes between `note` and `siteRoot`, from its parent up, following the
* first parent inside the site.
*/
export function getSiteAncestorIds(note: ShareNote, siteRoot: ShareNote) {
const ancestorIds: string[] = [];
for (let position = getSitePosition(note, siteRoot);
position && position.parent.noteId !== siteRoot.noteId;
position = getSitePosition(position.parent, siteRoot)) {
ancestorIds.push(position.parent.noteId);
}
return ancestorIds;
}
/**
* Returns the pages before and after `note` when the site starting at `siteRoot` is read in tree
* order: a page, then its children, then its next sibling. A note in several places follows the
* first parent inside the site. A note hidden from the tree has neither link. `isSubtreeHidden` names
* the notes whose children are left out of that order; a page below one of them has neither link.
*/
export function getPrevNextLinks(
note: ShareNote, siteRoot: ShareNote, isSubtreeHidden: (note: ShareNote) => boolean = () => false
) {
if (isInHiddenSubtree(note, siteRoot, isSubtreeHidden)) {
return { previous: null, next: null };
}
const getTreeChildren = (parent: ShareNote) => (isSubtreeHidden(parent) ? [] : parent.getVisibleChildNotes());
const previous = getPreviousPage(note, siteRoot, getTreeChildren);
const next = getNextPage(note, siteRoot, getTreeChildren);
return {
previous: previous && toPageLink(previous),
next: next && toPageLink(next)
};
}
/** Whether a note between `note` and `siteRoot` keeps its children out of the tree. */
function isInHiddenSubtree(note: ShareNote, siteRoot: ShareNote, isSubtreeHidden: (note: ShareNote) => boolean) {
for (let position = getSitePosition(note, siteRoot); position;
position = getSitePosition(position.parent, siteRoot)) {
if (isSubtreeHidden(position.parent)) {
return true;
}
}
return false;
}
function getPreviousPage(note: ShareNote, siteRoot: ShareNote, getTreeChildren: (note: ShareNote) => ShareNote[]) {
const position = getSitePosition(note, siteRoot);
if (!position) {
return null;
}
if (position.index === 0) {
return position.parent;
}
let previous = position.siblings[position.index - 1];
for (let children = getTreeChildren(previous); children.length;
children = getTreeChildren(previous)) {
previous = children[children.length - 1];
}
return previous;
}
function getNextPage(note: ShareNote, siteRoot: ShareNote, getTreeChildren: (note: ShareNote) => ShareNote[]) {
const notePosition = getSitePosition(note, siteRoot);
if (!notePosition && note.noteId !== siteRoot.noteId) {
return null;
}
const firstChild = getTreeChildren(note)[0];
if (firstChild) {
return firstChild;
}
for (let position = notePosition; position;
position = getSitePosition(position.parent, siteRoot)) {
const nextSibling = position.siblings[position.index + 1];
if (nextSibling) {
return nextSibling;
}
}
return null;
}
/**
* Returns where `note` stands among the visible children of its first parent inside the site, or
* `null` for the site root and for a note outside the site or hidden from the tree.
*/
function getSitePosition(note: ShareNote, siteRoot: ShareNote) {
if (note.noteId === siteRoot.noteId) {
return null;
}
const answers = new Map<string, boolean>();
const parent = note.getParentNotes().find((candidate) => isInSite(candidate, siteRoot, answers));
const siblings = parent?.getVisibleChildNotes() ?? [];
const index = siblings.findIndex((sibling) => sibling.noteId === note.noteId);
return parent && index !== -1 ? { parent, siblings, index } : null;
}
/**
* Whether `note` is `siteRoot` or below it. `answers` keeps the answer for each note checked, so
* that clones reached by many paths are checked once.
*/
function isInSite(note: ShareNote, siteRoot: ShareNote, answers: Map<string, boolean>): boolean {
let answer = answers.get(note.noteId);
if (answer === undefined) {
answer = note.noteId === siteRoot.noteId
|| note.getParentNotes().some((parent) => isInSite(parent, siteRoot, answers));
answers.set(note.noteId, answer);
}
return answer;
}
function toPageLink(note: ShareNote): PageLink {
return { title: note.title, href: `./${note.shareId}` };
}