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 } from "@triliumnext/commons";
import type { NoteMeta, NoteMetaFile } from "@triliumnext/core";
import { describe, expect, it } from "vitest";
import { buildHelpMeta, serializeHelpMeta, stripAppVersion } from "./help_meta_generator.js";
const BASE_URL = "https://docs.triliumnotes.org";
/** Wraps the given notes in a "User Guide" export root, mirroring the real markdown export. */
function metaFileOf(children: NoteMeta[], rootAttributes: NoteMeta["attributes"] = []): { formatVersion: number; appVersion: string; files: NoteMeta[] } {
const root: NoteMeta = {
isClone: false, noteId: "root", notePath: ["root"], title: "User Guide",
notePosition: 1, prefix: null, isExpanded: false, type: "text", mime: "text/html",
attributes: rootAttributes, format: "markdown", attachments: [],
dataFileName: "User Guide.md", dirFileName: "User Guide", children
};
return { formatVersion: 2, appVersion: "0.103.0", files: [root] };
}
const labelOf = (item: HelpMetaItem | undefined, name: string) =>
item?.attributes?.find((a) => a.name === name)?.value;
describe("buildHelpMeta", () => {
it("resolves structure, icons and content sources", () => {
const page: NoteMeta = {
isClone: false, noteId: "text1", title: "Text", type: "text", mime: "text/html",
attributes: [{ type: "label", name: "iconClass", value: "bx bx-star", isInheritable: false, position: 10 }],
format: "markdown", dataFileName: "Text.md", children: []
};
const folder: NoteMeta = {
isClone: false, noteId: "types", title: "Note Types", type: "text", mime: "text/html",
attributes: [], format: "markdown", dirFileName: "Note Types", children: [page]
};
const { meta: items, sources } = buildHelpMeta(metaFileOf([folder]));
const folderItem = items[0];
const pageItem = folderItem?.children?.[0];
// A note with no data file of its own is a folder: no source, but a directory, which is
// the only path other pages can link to it by.
expect(folderItem?.id).toBe("_help_types");
expect(folderItem?.type).toBe("book");
expect(sources._help_types?.source).toBeUndefined();
expect(sources._help_types?.dir).toBe("User Guide/Note Types");
expect(labelOf(folderItem, "iconClass")).toBe("bx bx-folder");
// Sources are relative to the export directory, which already is the root note's folder,
// so the root contributes exactly one path segment.
expect(pageItem?.id).toBe("_help_text1");
expect(pageItem?.type).toBe("text");
expect(sources._help_text1?.source).toBe("User Guide/Note Types/Text.md");
expect(labelOf(pageItem, "iconClass")).toBe("bx bx-star");
});
it("resolves a clone's icon and source to the primary occurrence", () => {
// The same note is placed under two folders: a primary occurrence (isClone:false) carrying
// a custom icon and the real file, and a clone (isClone:true) with no attributes and a
// ".clone" data file. Both are the same note, so both must describe it identically —
// otherwise the clone would point at a file that only exists to satisfy the export.
const primary: NoteMeta = {
isClone: false, noteId: "nix", title: "Nix flake", type: "text", mime: "text/html",
attributes: [{ type: "label", name: "iconClass", value: "bx bxl-tux", isInheritable: false, position: 10 }],
format: "markdown", dataFileName: "Nix flake.md", children: []
};
const clone: NoteMeta = {
isClone: true, noteId: "nix", title: "Nix flake", type: "text", mime: "text/html",
format: "markdown", dataFileName: "Nix flake.clone.md", children: []
};
const desktop: NoteMeta = {
isClone: false, noteId: "desktop", title: "Desktop Installation", type: "text", mime: "text/html",
attributes: [], format: "markdown", dirFileName: "Desktop Installation", children: [primary]
};
const server: NoteMeta = {
isClone: false, noteId: "server", title: "Server Installation", type: "text", mime: "text/html",
attributes: [], format: "markdown", dirFileName: "Server Installation", children: [clone]
};
const { meta: items, sources } = buildHelpMeta(metaFileOf([desktop, server]));
const primaryItem = items.find((i) => i.id === "_help_desktop")?.children?.[0];
const cloneItem = items.find((i) => i.id === "_help_server")?.children?.[0];
expect(primaryItem?.id).toBe("_help_nix");
expect(cloneItem?.id).toBe("_help_nix");
expect(labelOf(cloneItem, "iconClass")).toBe("bx bxl-tux");
// Both occurrences are the one note, so they leave one source between them — the primary's
// file rather than the ".clone" copy the export wrote beside it.
expect(sources._help_nix?.source).toBe("User Guide/Desktop Installation/Nix flake.md");
});
it("derives docUrl from the share alias chain, and only when a base URL is given", () => {
const page: NoteMeta = {
isClone: false, noteId: "highlights", title: "Feature Highlights", type: "text", mime: "text/html",
attributes: [{ type: "label", name: "shareAlias", value: "feature-highlights", isInheritable: false, position: 10 }],
format: "markdown", dataFileName: "Feature Highlights.md", children: []
};
const rootAlias: NoteMeta["attributes"] = [
{ type: "label", name: "shareAlias", value: "user-guide", isInheritable: false, position: 10 }
];
const { meta: withBase } = buildHelpMeta(metaFileOf([page], rootAlias), BASE_URL);
expect(labelOf(withBase[0], "docUrl")).toBe("https://docs.triliumnotes.org/user-guide/feature-highlights");
const { meta: withoutBase } = buildHelpMeta(metaFileOf([page], rootAlias));
expect(labelOf(withoutBase[0], "docUrl")).toBeUndefined();
});
it("keeps web views pointing at the online docs and gives them no source", () => {
const embedded: NoteMeta = {
isClone: false, noteId: "embedded", title: "Embedded", type: "webView", mime: "",
attributes: [{ type: "label", name: "webViewSrc", value: "/user-guide/embedded", isInheritable: false, position: 10 }],
format: "markdown", dataFileName: "Embedded.md", children: []
};
const { meta: items, sources } = buildHelpMeta(metaFileOf([embedded]), BASE_URL);
expect(items[0]?.type).toBe("webView");
expect(sources._help_embedded?.source).toBeUndefined();
// Root-relative sources are stored that way in the notes; the docs origin is applied here.
expect(labelOf(items[0], "webViewSrc")).toBe("https://docs.triliumnotes.org/user-guide/embedded");
});
it("keeps the full content width of a page", () => {
const page = (noteId: string, attributes: NoteMeta["attributes"]): NoteMeta => ({
isClone: false, noteId, title: noteId, type: "text", mime: "text/html",
attributes, format: "markdown", dataFileName: `${noteId}.md`, children: []
});
const wide = page("wide", [{ type: "label", name: "fullContentWidth", value: "", isInheritable: false, position: 10 }]);
const narrow = page("narrow", []);
const { meta: items } = buildHelpMeta(metaFileOf([ wide, narrow ]));
expect(items[0]?.attributes?.find((a) => a.name === "fullContentWidth")).toBeDefined();
expect(items[1]?.attributes?.find((a) => a.name === "fullContentWidth")).toBeUndefined();
});
it("keeps the mime of code notes so their content is not treated as markdown", () => {
const script: NoteMeta = {
isClone: false, noteId: "script", title: "Example", type: "code", mime: "application/javascript;env=backend",
attributes: [], format: "markdown", dataFileName: "Example.js", children: []
};
const { meta: items, sources } = buildHelpMeta(metaFileOf([script]));
expect(items[0]?.type).toBe("code");
expect(items[0]?.mime).toBe("application/javascript;env=backend");
expect(sources._help_script?.source).toBe("User Guide/Example.js");
});
it("hides notes that are hidden from the share tree", () => {
const hidden: NoteMeta = {
isClone: false, noteId: "hidden", title: "Features", type: "text", mime: "text/html",
attributes: [{ type: "label", name: "shareHiddenFromTree", value: "", isInheritable: false, position: 10 }],
format: "markdown", dirFileName: "Features", children: []
};
expect(buildHelpMeta(metaFileOf([hidden])).meta).toHaveLength(0);
});
it("returns nothing when the export has no files", () => {
expect(buildHelpMeta({ formatVersion: 2, appVersion: "0.103.0", files: undefined as never }))
.toEqual({ meta: [], sources: {} });
});
});
describe("stripAppVersion", () => {
it("drops the version stamp and keeps everything else the docs metadata carries", () => {
const meta = {
formatVersion: 2,
appVersion: "0.105.0",
files: [{ noteId: "abc", title: "Note", attributes: [] }]
} as unknown as NoteMetaFile;
const stripped = stripAppVersion(meta);
expect("appVersion" in stripped).toBe(false);
expect(stripped).toStrictEqual({ formatVersion: 2, files: meta.files });
// The input is left alone: the help tree is derived from the same object afterwards.
expect(meta.appVersion).toBe("0.105.0");
});
});
describe("serializeHelpMeta", () => {
it("writes each note on a line of its own and parses back to the same tree", () => {
const tree: HelpMetaItem[] = [
{
id: "_help_a",
title: "Folder",
type: "book",
attributes: [ { type: "label", name: "iconClass", value: "bx" } ],
children: [
{ id: "_help_b", title: "Page", type: "text" },
{ id: "_help_c", title: "Script", type: "code", mime: "text/x", children: [] }
]
},
{ id: "_help_d", title: "Web view", type: "webView" }
];
const json = serializeHelpMeta(tree);
expect(JSON.parse(json)).toStrictEqual(tree);
expect(json.split("\n")).toStrictEqual([
"[",
` {"id":"_help_a","title":"Folder","type":"book",` +
`"attributes":[{"type":"label","name":"iconClass","value":"bx"}],"children":[`,
` {"id":"_help_b","title":"Page","type":"text"},`,
` {"id":"_help_c","title":"Script","type":"code","mime":"text/x","children":[]}`,
" ]},",
` {"id":"_help_d","title":"Web view","type":"webView"}`,
"]"
]);
expect(serializeHelpMeta([])).toBe("[]");
});
});