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
import type { HelpMetaItem, HiddenSubtreeAttribute } from "@triliumnext/commons";
import type { NoteMeta, NoteMetaFile } from "@triliumnext/core";
/**
* Builds the in-app help tree from the User Guide's markdown export meta.
*
* The tree describes the `_help` subtree the application injects into becca; the files backing it
* come back beside it rather than within it, since which markdown produced a page is of no use to
* anything past the build. Rendering that markdown into the page content the app displays is the
* build's job too, not this module's — here we only resolve structure, identity and the labels
* the notes carry.
*
* @param noteMetaFile the `!!!meta.json` written next to the markdown export.
* @param baseUrl root of the online documentation, used to resolve the canonical page URLs
* (`docUrl`) and to absolutise root-relative web view sources.
*/
export function buildHelpMeta(noteMetaFile: NoteMetaFile, baseUrl?: string): HelpMetaResult {
if (!noteMetaFile.files) {
console.warn("No meta files found to parse.");
return { meta: [], sources: {} };
}
const metaRoot = noteMetaFile.files[0];
// A note cloned into several help locations appears once per location, but only one of the
// occurrences is the real thing: the others carry no attributes and a ".clone" data file.
// Index the primary occurrence's values up front so every clone can reuse them.
const canonicalByNoteId = new Map<string, CanonicalOccurrence>();
indexPrimaryOccurrences(metaRoot, "", canonicalByNoteId);
// Sources are relative to the export directory, which is the root note's own directory, so
// the walk starts empty and picks up that directory on its first step down. The documentation
// root doubles as the parent URL every page's share alias is appended to.
const sources: HelpSources = {};
const parsedMetaRoot = parseNoteMeta(metaRoot, "", canonicalByNoteId, sources, baseUrl, baseUrl);
return { meta: parsedMetaRoot?.children ?? [], sources };
}
/** The help tree, and the export files each of its notes was built from. */
export interface HelpMetaResult {
meta: HelpMetaItem[];
sources: HelpSources;
}
/**
* Where each note's content came from, by note ID. Only the build has any use for it: the bundler
* reads the pages through it and resolves the links between them, and then it is thrown away
* rather than shipped.
*/
export type HelpSources = Record<string, HelpPageSource>;
export interface HelpPageSource {
/**
* Content file, relative to the markdown export root (e.g. `User Guide/Note Types/Text.md`).
* Absent for folders and web views, which have no file of their own. Clones point at the
* primary occurrence's file rather than their own `.clone` copy.
*/
source?: string;
/**
* Directory this note's children live in, relative to the markdown export root. Set for every
* note that has one, and the only way to address a folder note: it has no file of its own, so
* pages link to it by its directory.
*/
dir?: string;
}
/**
* Drops the app version the exporter stamps onto a meta file. Nothing reads it back — neither the
* importer nor {@link parseNoteMetaFile} — while it moves on every release, so keeping it rewrites
* the committed documentation metadata for a field no code consults. An export a user takes of
* their own notes keeps it, as a record of the build that wrote the zip.
*/
export function stripAppVersion(meta: NoteMetaFile): Omit<NoteMetaFile, "appVersion"> {
const { appVersion, ...rest } = meta;
return rest;
}
/**
* Serializes the help tree with one note per line, its children indented below it, so a docs
* change shows up in a diff as the notes it touched.
*/
export function serializeHelpMeta(items: HelpMetaItem[], depth = 0): string {
if (!items.length) {
return "[]";
}
const indent = " ".repeat(depth + 1);
const lines: string[] = [];
for (const item of items) {
const { children, ...fields } = item;
if (!children?.length) {
lines.push(indent + JSON.stringify(item));
continue;
}
const ownFields = JSON.stringify(fields).slice(0, -1);
lines.push(`${indent}${ownFields},"children":${serializeHelpMeta(children, depth + 1)}}`);
}
return `[\n${lines.join(",\n")}\n${" ".repeat(depth)}]`;
}
interface CanonicalOccurrence {
iconClass: string;
source?: string;
}
function parseNoteMeta(
noteMeta: NoteMeta,
sourceRoot: string,
canonicalByNoteId: Map<string, CanonicalOccurrence>,
sources: HelpSources,
baseUrl?: string,
parentUrl?: string
): HelpMetaItem | null {
const attributes: HiddenSubtreeAttribute[] = [];
// Build the online URL for this note; only notes with a share alias of their own are
// published, the rest just pass their parent's URL down to their children.
const shareAlias = noteMeta.attributes?.find((a) => a.type === "label" && a.name === "shareAlias")?.value;
const currentUrl = parentUrl && shareAlias ? `${parentUrl}/${shareAlias}` : parentUrl;
for (const attribute of noteMeta.attributes ?? []) {
if (attribute.name === "shareHiddenFromTree") {
return null;
}
if (attribute.name === "webViewSrc") {
attributes.push({
type: "label",
name: "webViewSrc",
// Web views pointing inside the documentation are stored root-relative.
value: absolutiseUrl(attribute.value, baseUrl)
});
}
if (attribute.type === "label" && attribute.name === "fullContentWidth") {
attributes.push({ type: "label", name: "fullContentWidth", value: attribute.value });
}
}
if (shareAlias && currentUrl) {
attributes.push({ type: "label", name: "docUrl", value: currentUrl });
}
// Clones share the underlying note, so resolve their icon and content file to the primary
// occurrence's; otherwise the two occurrences would describe the same note differently.
const canonical = noteMeta.isClone ? canonicalByNoteId.get(noteMeta.noteId ?? "") : undefined;
attributes.push({
type: "label",
name: "iconClass",
value: canonical?.iconClass ?? computeIconClass(noteMeta)
});
const item: HelpMetaItem = {
id: `_help_${noteMeta.noteId}`,
title: noteMeta.title ?? "",
type: resolveType(noteMeta),
attributes
};
if (item.type === "code") {
item.mime = noteMeta.mime;
}
const source = item.type === "text" || item.type === "code"
? canonical?.source ?? computeSource(sourceRoot, noteMeta.dataFileName)
: undefined;
const dir = noteMeta.dirFileName ? computeSource(sourceRoot, noteMeta.dirFileName) : undefined;
if (source || dir) {
sources[item.id] = { source, dir };
}
if (noteMeta.children) {
const childSourceRoot = noteMeta.dirFileName ? `${sourceRoot}/${noteMeta.dirFileName}` : sourceRoot;
const children: HelpMetaItem[] = [];
for (const childMeta of noteMeta.children) {
const child = parseNoteMeta(childMeta, childSourceRoot, canonicalByNoteId, sources, baseUrl, currentUrl);
if (child) {
children.push(child);
}
}
item.children = children;
}
return item;
}
/**
* A note with no data file of its own is a pure folder. Web views render a remote page, so their
* data file (if any) is irrelevant. Everything else carries content built from its source file.
*/
function resolveType(noteMeta: NoteMeta): HelpMetaItem["type"] {
if (noteMeta.type === "webView") {
return "webView";
}
if (!noteMeta.dataFileName) {
return "book";
}
return noteMeta.type === "code" ? "code" : "text";
}
/** Records the icon and content file of every primary (non-clone) occurrence, for its clones. */
function indexPrimaryOccurrences(noteMeta: NoteMeta, sourceRoot: string, out: Map<string, CanonicalOccurrence>): void {
if (!noteMeta.isClone && noteMeta.noteId) {
out.set(noteMeta.noteId, {
iconClass: computeIconClass(noteMeta),
source: computeSource(sourceRoot, noteMeta.dataFileName)
});
}
if (noteMeta.children) {
const childSourceRoot = noteMeta.dirFileName ? `${sourceRoot}/${noteMeta.dirFileName}` : sourceRoot;
for (const childMeta of noteMeta.children) {
indexPrimaryOccurrences(childMeta, childSourceRoot, out);
}
}
}
function computeIconClass(noteMeta: NoteMeta): string {
// An explicit iconClass wins; otherwise folders default to bx-folder and files to bx-file.
const explicit = noteMeta.attributes?.find((a) => a.name === "iconClass")?.value;
if (explicit) {
return explicit;
}
return noteMeta.dataFileName ? "bx bx-file" : "bx bx-folder";
}
function computeSource(sourceRoot: string, dataFileName?: string): string | undefined {
if (!dataFileName) {
return undefined;
}
// The walk seeds the root as an empty string, so every path picked up along the way carries a
// leading separator that has to come back off.
return `${sourceRoot}/${dataFileName}`.substring(1);
}
function absolutiseUrl(url: string | undefined, baseUrl?: string): string | undefined {
if (url?.startsWith("/") && baseUrl) {
return `${baseUrl}${url}`;
}
return url;
}