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
chore(skills): point docs.mjs at the help artifacts
Elian Doran78f81a5fe1fa
diff --git a/.claude/skills/writing-documentation/SKILL.md b/.claude/skills/writing-documentation/SKILL.mdindex 00453d1901..2a7da2bb9b 100644--- a/.claude/skills/writing-documentation/SKILL.md+++ b/.claude/skills/writing-documentation/SKILL.md@@ -1,15 +1,16 @@---name: writing-documentation-description: Use whenever a change is user-facing — a new feature, a moved or removed button, a label, a shortcut, an option, a default, a note type, a collection view, a dialog, an import format — or when asked to write, fix, restructure or audit Trilium's documentation ("document this", "update the User Guide", "add a page for X", "is X documented?", "which page describes X?", "the docs still say…", "rename/move this page", "add a screenshot", "which icon do I use?"). Covers the three docs trees (`docs/User Guide`, `docs/Developer Guide`, `docs/Release Notes`) and the generated in-app help they feed, the `!!!meta.json` note metadata (noteId, shareAlias, iconClass, attachments), the house style of the User Guide (register, page templates, reference-link pills, `<kbd>`, admonitions, figures, the `bx`/`cke`/`tn-brand` icon spans), and `docs.mjs`, which finds and shows pages, scaffolds a page with correct metadata, registers images, renames/moves/deletes pages, maps a code diff to the pages it affects, audits the trees, and regenerates the help HTML headless — so `!!!meta.json` and `apps/server/src/assets/doc_notes` never have to be read or hand-edited. A user-facing change is not finished until the User Guide describes it, in the same commit.+description: Use whenever a change is user-facing — a new feature, a moved or removed button, a label, a shortcut, an option, a default, a note type, a collection view, a dialog, an import format — or when asked to write, fix, restructure or audit Trilium's documentation ("document this", "update the User Guide", "add a page for X", "is X documented?", "which page describes X?", "the docs still say…", "rename/move this page", "add a screenshot", "which icon do I use?"). Covers the three docs trees (`docs/User Guide`, `docs/Developer Guide`, `docs/Release Notes`) and the generated in-app help they feed, the `!!!meta.json` note metadata (noteId, shareAlias, iconClass, attachments), the house style of the User Guide (register, page templates, reference-link pills, `<kbd>`, admonitions, figures, the `bx`/`cke`/`tn-brand` icon spans), and `docs.mjs`, which finds and shows pages, scaffolds a page with correct metadata, registers images, renames/moves/deletes pages, maps a code diff to the pages it affects, audits the trees, and regenerates the in-app help headless — so `!!!meta.json` and `apps/server/src/assets/help` never have to be read or hand-edited. A user-facing change is not finished until the User Guide describes it, in the same commit.---# Writing Trilium's documentationTrilium's User Guide is a tree of Trilium notes, exported to Markdown under `docs/User Guide/` anddescribed by `docs/User Guide/!!!meta.json`. From that Markdown the repo generates the **in-app help**-(`apps/server/src/assets/doc_notes/en/User Guide/**/*.html` + a minified help meta, and-`apps/standalone/src/assets/help_meta.json`) and the public site (docs.triliumnotes.org). The Markdown-is the source; everything under `doc_notes` and `help_meta.json` is generated and never hand-edited.+(`apps/server/src/assets/help/help_meta.json`, the tree, and `help_content.json`, each page's HTML)+and the public site (docs.triliumnotes.org). The Markdown is the source; both help files are+generated and never hand-edited. The help pages are virtual notes built from them at startup, not+notes in the database.Every mechanical step is [docs.mjs](docs.mjs):@@ -23,7 +24,7 @@ node $D new Collections "Timeline" --icon bx-time-five --after Dashboard # scanode $D image timeline shot.png # register a screenshot; prints the <figure> to pastenode $D icons quote --pack cke # icon classes for a toolbar button / app controlnode $D rename timeline "Timeline view" # retitle; move <page> <parent>; delete <page>-node $D sync # regenerate Markdown, help HTML and help metas headless+node $D sync # regenerate Markdown and both help artifacts headlessnode $D check # meta ↔ disk, links, images, icons, aliases, code refs, style```@@ -41,11 +42,11 @@ The workflow, every time:for the names the diff cannot know. **Read every hit** — a page describing a control that moved,a label that changed or a default that flipped is wrong until edited.2. Edit the Markdown (below), or `new` a page for a feature no page covers.-3. `node $D sync` — normalizes your Markdown the way the editor would and regenerates the help HTML- and both help metas. Review `git diff -- docs` (what the round trip did to your text) and- `git diff --stat -- apps/server/src/assets/doc_notes`.+3. `node $D sync` — normalizes your Markdown the way the editor would and regenerates both help+ artifacts. Review `git diff -- docs` (what the round trip did to your text) and+ `git diff --word-diff -- apps/server/src/assets/help/help_content.json`.4. `node $D check` — must report 0 errors (a handful are pre-existing, listed at the end).-5. Commit the code, the Markdown, `!!!meta.json`, the `doc_notes` HTML and `help_meta.json` together.+5. Commit the code, the Markdown, `!!!meta.json`, `help_meta.json` and `help_content.json` together.Two traps `CLAUDE.md` names still apply: verify **where a control actually mounts** by grepping thecomponent, not by inference; and a widened **capability gate** (a note type added to a list a widget@@ -95,13 +96,12 @@ paste into the parent page. Then write the body, `image` the screenshots, `sync`- **Alias** defaults to the kebab-case title; pass `--alias` to shorten (`setup`, `docker`, `mfa`,`and` for `&`). The public URL is the chain of ancestor aliases, so it only has to be unique among- siblings; a page without one has no URL and is dropped from the standalone help. Once published, an+ siblings; a page without one has no public URL and no `docUrl` in the in-app help. Once published, analias is an external link (README ×41, website, web clipper, about dialog) — `show` lists who uses it.- **Icon**: the feature's own icon — a note type's `NOTE_TYPE_ICONS` entry, a collection's templateicon in `hidden_subtree_templates.ts`, otherwise `icons <query>`. Boxicons (`bx bx-…`) only for`iconClass`.-- **Title characters**: letters, digits, space, `_ - ( ) & . , \``. The in-app help refuses anything- else (`doc_renderer.ts`), and `new` refuses too. `/`, `:` and `"` are dropped from the file name.+- **Title characters**: `/ \ : * ? " < > |` are dropped from the file name.- **Wire it into the app** when the page documents a surface with a help affordance: `<HelpButtonhelpPage="<noteId>">` (settings panes, dialogs), `helpPageId` on a `Modal`, or the maps in`apps/client/src/services/in_app_help.ts` (`byNoteType`, `byBookType`, sidebar sections). The appdiff --git a/.claude/skills/writing-documentation/docs.mjs b/.claude/skills/writing-documentation/docs.mjsindex 168538c548..ccbff45985 100644--- a/.claude/skills/writing-documentation/docs.mjs+++ b/.claude/skills/writing-documentation/docs.mjs@@ -16,15 +16,15 @@* icons <query...> [--pack bx|cke|tn-brand] search the icon fonts the docs can use* impact [--diff [range]] [terms...] which pages a code change or a term touches* check [--tree t] consistency + style audit of the trees- * sync regenerate everything (help HTML, meta) headless+ * sync regenerate everything (help meta + content) headless** <page> a noteId, a shareAlias, or a unique title/path fragment. <parent> likewise.* --tree user (default) | dev | release*- * The meta file is 6000+ lines and the HTML mirror is generated, so nothing here should ever- * need either read by hand. `new`/`image`/`rename`/`move`/`delete` edit `!!!meta.json` through- * the file's own layout (4-space indent, exporter key order); `sync` then makes the Markdown,- * the help HTML and the standalone meta agree, the same way edit-docs does after an edit.+ * The meta file is 6000+ lines and the in-app help artifacts are generated, so nothing here should+ * ever need either read by hand. `new`/`image`/`rename`/`move`/`delete` edit `!!!meta.json`+ * through the file's own layout (4-space indent, exporter key order); `sync` then makes the+ * Markdown, `help_meta.json` and `help_content.json` agree, the same way edit-docs does after an edit.*/import { execFileSync, spawnSync } from "node:child_process";import crypto from "node:crypto";@@ -43,9 +43,8 @@ const TREES = {user: {dir: "docs/User Guide",rootId: "pOsGYCXsbNQG",- html: "apps/server/src/assets/doc_notes/en/User Guide",- helpMeta: "apps/server/src/assets/doc_notes/en/User Guide/!!!meta.json",- standaloneMeta: "apps/standalone/src/assets/help_meta.json"+ helpMeta: "apps/server/src/assets/help/help_meta.json",+ helpContent: "apps/server/src/assets/help/help_content.json"},dev: { dir: "docs/Developer Guide", rootId: "jdjRLhLV3TtI" },release: { dir: "docs/Release Notes", rootId: "hD3V4hiu2VW4" }@@ -65,9 +64,6 @@ const BUILT_ICON_PACKS = {"tn-brand": { font: "brand-icons.woff2", missing: () => staleBrandIcons() }};-/** `apps/client/src/services/doc_renderer.ts` refuses any other character in a help page path. */-const DOC_NAME_CHARS = /^[a-zA-Z0-9_/\- ()&.,`]+$/;-/** Where the app hard-codes help pages (by noteId) and public docs URLs (by alias path). */const CODE_SCAN_DIRS = ["apps/client/src", "apps/server/src", "apps/desktop/src", "apps/standalone/src", "apps/website/src", "apps/web-clipper", "apps/edit-docs/demo", "packages/trilium-core/src", "packages/commons/src"];const URL_SCAN_FILES = ["README.md", ...CODE_SCAN_DIRS];@@ -131,9 +127,8 @@ function show() {console.log(` path ${page.ancestors.map((a) => a.title).concat(page.title).join(" › ")}`);console.log(` position ${page.entry.notePosition ?? "(clone)"} siblings: ${page.parent ? page.parent.entry.children.length : 0}`);console.log(` type ${page.entry.type}${page.entry.mime ? ` (${page.entry.mime})` : ""}`);- console.log(` alias ${page.alias ?? "(none — no docUrl, dropped from the standalone help)"}`);+ console.log(` alias ${page.alias ?? "(none — no public URL, no docUrl in the in-app help)"}`);console.log(` url ${page.url ?? "(none)"}`);- if (page.treeName === "user") console.log(` docName ${page.docName ?? "(none)"}`);console.log(` icon ${page.icon ?? "(none → bx bx-file / bx bx-folder)"}`);const otherAttrs = (page.entry.attributes ?? []).filter((a) => !["shareAlias", "iconClass"].includes(a.name));if (otherAttrs.length) console.log(` attributes ${otherAttrs.map((a) => `${a.type === "relation" ? "~" : "#"}${a.name}=${a.value}`).join(" ")}`);@@ -162,8 +157,8 @@ function show() {console.log(` referenced from code: ${refs.length ? "" : "none — safe to rename, move or delete"}`);for (const r of refs) console.log(` ${r}`);if (page.treeName === "user" && page.file) {- const html = page.file.replace(/\.md$/, ".html").replace(TREES.user.dir, TREES.user.html);- console.log(` help html ${fs.existsSync(path.join(ROOT, html)) ? html : "(missing — run sync)"}`);+ const html = readHelpContent()[`_help_${page.noteId}`];+ console.log(` help html ${html === undefined ? "(missing — run sync)" : `${html.length} chars in ${TREES.user.helpContent}`}`);}}@@ -240,7 +235,7 @@ function newPage() {console.log(`created ${filePath}`);console.log(` noteId ${noteId} alias ${alias ?? "(none)"} icon ${icon ?? "(none)"} position ${entry.notePosition}`);if (alias) console.log(` url ${computeUrl(parent, alias)}`);- console.log(`\nWrite the page, then \`docs.mjs sync\` to normalize it and generate the help HTML.`);+ console.log(`\nWrite the page, then \`docs.mjs sync\` to normalize it and regenerate the in-app help.`);console.log(`Link it from its parent with:\n <a class="reference-link" href="${relativeHref(parent, { ...entry, file: filePath })}">${escapeHtml(title)}</a>`);}@@ -272,7 +267,7 @@ function image() {} else {console.log(` <img src="${src}">`);}- console.log(`Then \`docs.mjs sync\` copies it into the help HTML tree.`);+ console.log(`Then \`docs.mjs sync\` rewrites its path in the in-app help.`);}function rename() {@@ -394,7 +389,7 @@ function impact() {const pagesFromCode = new Map(); // noteId → filesif (flags.diff !== undefined) {const range = typeof flags.diff === "string" ? flags.diff : defaultDiffBase();- const diff = git(["diff", range, "--", "apps", "packages", ":!apps/server/src/assets/doc_notes", ":!apps/standalone/src/assets/help_meta.json"]);+ const diff = git(["diff", range, "--", "apps", "packages", `:!${TREES.user.helpMeta}`, `:!${TREES.user.helpContent}`]);let file = "";const touched = new Set();for (const line of diff.split("\n")) {@@ -456,7 +451,7 @@ function check() {const index = loadTree(treeName);checkStructure(index, errors, warnings);checkContent(index, errors, warnings);- if (treeName === "user") checkHtmlMirror(index, errors, warnings);+ if (treeName === "user") checkHelpArtifacts(index, errors, warnings);}warnings.push(...staleIconFonts(Object.keys(BUILT_ICON_PACKS)));if (trees.includes("user")) {@@ -480,12 +475,11 @@ function sync() {die("sync failed — the import rejects a tree whose !!!meta.json and files disagree; run `check`");}const after = gitStatusDocs();- const groups = { "docs/ Markdown": [], "docs/ !!!meta.json": [], "help HTML (doc_notes)": [], "help meta": [], images: [] };+ const groups = { "docs/ Markdown": [], "docs/ !!!meta.json": [], "help artifacts": [], images: [] };for (const [status, file] of after) {const bucket = /!!!meta\.json$/.test(file) && file.startsWith("docs/") ? "docs/ !!!meta.json"- : /help_meta\.json$|doc_notes.*!!!meta\.json$/.test(file) ? "help meta": /\.(png|gif|webp|jpe?g|svg)$/i.test(file) ? "images"- : file.startsWith("docs/") ? "docs/ Markdown" : "help HTML (doc_notes)";+ : file.startsWith("docs/") ? "docs/ Markdown" : "help artifacts";groups[bucket].push(`${status} ${file}`);}const changedBySync = after.filter(([, f]) => !before.some(([, g]) => g === f)).length;@@ -496,7 +490,7 @@ function sync() {for (const f of files.slice(0, 8)) console.log(` ${f}`);if (files.length > 8) console.log(` … ${files.length - 8} more`);}- console.log(`\nReview with \`git diff -- docs\` (your Markdown, normalized) and \`git diff --stat -- apps/server/src/assets/doc_notes\`.`);+ console.log(`\nReview with \`git diff -- docs\` (your Markdown, normalized) and \`git diff --word-diff -- ${TREES.user.helpContent}\`.`);console.log(`Reflow, shifted and <li><p> churn in the HTML is expected; a changed href, a dropped <img> or lost text is not.`);}@@ -555,9 +549,8 @@ function checkStructure(index, errors, warnings) {if (i > 0 && siblings[i - 1].notePosition > page.entry.notePosition) errors.push(`${where}: children are not in ascending notePosition order`);else if (i > 0 && siblings[i - 1].notePosition === page.entry.notePosition) warnings.push(`${where}: shares notePosition ${page.entry.notePosition} with "${siblings[i - 1].title}"`);}- if (treeName === "user" && page.docName && !DOC_NAME_CHARS.test(page.docName)) errors.push(`${where}: title/folder has a character the in-app help refuses (allowed: letters, digits, _ - ( ) & . , \` and space)`);if (page.entry.type === "text" && page.file && treeName !== "release") {- if (!page.alias) warnings.push(`${where}: no shareAlias — no public URL, and dropped from the standalone help`);+ if (!page.alias) warnings.push(`${where}: no shareAlias — no public URL`);if (!page.icon && treeName === "user") warnings.push(`${where}: no iconClass`);}if (page.alias && !/^[a-z0-9]+([.-][a-z0-9]+)*$/.test(page.alias)) warnings.push(`${where}: shareAlias "${page.alias}" is not kebab-case`);@@ -639,14 +632,16 @@ function checkContent(index, errors, warnings) {}}-function checkHtmlMirror(index, errors, warnings) {+function checkHelpArtifacts(index, errors, warnings) {const status = gitStatusDocs();const modifiedMd = status.filter(([, f]) => f.startsWith(`${TREES.user.dir}/`) && f.endsWith(".md")).map(([, f]) => f);+ const content = readHelpContent();for (const page of index.pages) {- if (!page.file || page.depth === 0) continue;- const html = page.file.replace(/\.md$/, ".html").replace(TREES.user.dir, TREES.user.html);- if (page.file.endsWith(".md") && !fs.existsSync(path.join(ROOT, html))) { errors.push(`user: ${page.relPath} has no help HTML twin — run \`sync\``); continue; }- if (modifiedMd.includes(page.file) && !status.some(([, f]) => f === html)) warnings.push(`user: ${page.relPath} is modified but its help HTML is not — run \`sync\``);+ if (!page.file?.endsWith(".md") || page.depth === 0 || page.isClone) continue;+ if (content[`_help_${page.noteId}`] === undefined) errors.push(`user: ${page.relPath} has no entry in ${TREES.user.helpContent} — run \`sync\``);+ }+ if (modifiedMd.length && !status.some(([, f]) => f === TREES.user.helpContent)) {+ warnings.push(`user: ${modifiedMd.length} page(s) modified but ${TREES.user.helpContent} is not — run \`sync\``);}const helpMeta = JSON.parse(fs.readFileSync(path.join(ROOT, TREES.user.helpMeta), "utf-8"));const helpIds = new Set();@@ -703,7 +698,7 @@ function checkIconUsage(index) {// Tree model// ----------------------------------------------------------------------------------------------/** Reads a tree's `!!!meta.json` and indexes every entry with its path, URL and docName. */+/** Reads a tree's `!!!meta.json` and indexes every entry with its path and URL. */function loadTree(treeName) {if (treeCache.has(treeName)) return treeCache.get(treeName);const tree = TREES[treeName];@@ -712,7 +707,7 @@ function loadTree(treeName) {const raw = fs.readFileSync(metaPath, "utf-8");const meta = JSON.parse(raw);const index = { treeName, tree, meta, metaPath, raw, pages: [], byId: new Map(), root: null };- const visit = (entry, parent, dir, parentUrl, docNameRoot) => {+ const visit = (entry, parent, dir, parentUrl) => {const alias = entry.attributes?.find((a) => a.type === "label" && a.name === "shareAlias")?.value;const currentUrl = parentUrl && alias ? `${parentUrl}/${alias}` : parentUrl;const page = {@@ -726,15 +721,13 @@ function loadTree(treeName) {children: []};page.relPath = page.file ?? path.join(dir, entry.dirFileName ?? entry.title);- page.docName = treeName === "user" && entry.type === "text" && entry.dataFileName ? `${docNameRoot}/${path.basename(entry.dataFileName, ".md")}`.substring(1) : undefined;index.pages.push(page);if (!page.isClone) index.byId.set(entry.noteId, page);const childDir = entry.dirFileName ? path.join(dir, entry.dirFileName) : dir;- const childDocRoot = entry.dirFileName ? `${docNameRoot}/${entry.dirFileName}` : docNameRoot;- for (const child of entry.children ?? []) page.children.push(visit(child, page, childDir, currentUrl, childDocRoot));+ for (const child of entry.children ?? []) page.children.push(visit(child, page, childDir, currentUrl));return page;};- index.root = visit(meta.files[0], null, tree.dir, BASE_URL, `/${meta.files[0].dirFileName ?? ""}`);+ index.root = visit(meta.files[0], null, tree.dir, BASE_URL);treeCache.set(treeName, index);return index;}@@ -859,8 +852,6 @@ function otherTreesHave(id) {function checkTitle(title, parent, self) {if (!title.trim()) die("empty title");- const docName = `${parent ? childrenDir(parent) : ""}/${sanitize(title)}`;- if (parent && parent.treeName === "user" && !DOC_NAME_CHARS.test(docName.replace(/^docs\/User Guide\//, ""))) die(`the in-app help cannot open a page whose title has characters outside letters, digits, _ - ( ) & . , \` and space: "${title}"`);const fileBase = sanitize(title).toLowerCase();for (const c of parent?.entry.children ?? []) {if (c === self?.entry) continue;@@ -1011,7 +1002,7 @@ function unescapeHtml(s) {function grep(pattern, paths) {const existing = paths.filter((p) => fs.existsSync(path.join(ROOT, p)));- const result = spawnSync("grep", ["-rnoE", "--include=*.ts", "--include=*.tsx", "--include=*.js", "--include=*.json", "--include=*.md", "--include=*.html", "--exclude-dir=node_modules", "--exclude-dir=dist", "--exclude-dir=doc_notes", "--exclude=help_meta.json", pattern, ...existing], { cwd: ROOT, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 });+ const result = spawnSync("grep", ["-rnoE", "--include=*.ts", "--include=*.tsx", "--include=*.js", "--include=*.json", "--include=*.md", "--include=*.html", "--exclude-dir=node_modules", "--exclude-dir=dist", "--exclude=help_meta.json", "--exclude=help_content.json", pattern, ...existing], { cwd: ROOT, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 });return (result.stdout ?? "").split("\n").filter(Boolean);}@@ -1019,8 +1010,12 @@ function git(argv) {return execFileSync("git", argv, { cwd: ROOT, encoding: "utf-8", maxBuffer: 256 * 1024 * 1024 });}+function readHelpContent() {+ return JSON.parse(fs.readFileSync(path.join(ROOT, TREES.user.helpContent), "utf-8"));+}+function gitStatusDocs() {- return git(["status", "--porcelain", "--", "docs", TREES.user.html, TREES.user.standaloneMeta]).split("\n").filter(Boolean).map((l) => [l.slice(0, 2).trim() || "M", l.slice(3).replace(/^"|"$/g, "").replace(/\\"/g, '"')]);+ return git(["status", "--porcelain", "--", "docs", TREES.user.helpMeta, TREES.user.helpContent]).split("\n").filter(Boolean).map((l) => [l.slice(0, 2).trim() || "M", l.slice(3).replace(/^"|"$/g, "").replace(/\\"/g, '"')]);}function defaultDiffBase() {diff --git a/.claude/skills/writing-documentation/references/pipeline.md b/.claude/skills/writing-documentation/references/pipeline.mdindex 62759cebb5..1f9de0e106 100644--- a/.claude/skills/writing-documentation/references/pipeline.md+++ b/.claude/skills/writing-documentation/references/pipeline.md@@ -4,7 +4,7 @@| Tree | Root noteId | Source | Generated from it || --- | --- | --- | --- |-| User Guide | `pOsGYCXsbNQG` | `docs/User Guide/` (Markdown + `!!!meta.json`) | `apps/server/src/assets/doc_notes/en/User Guide/**/*.html` + its minified `!!!meta.json`; `apps/standalone/src/assets/help_meta.json`; `site/user-guide` on the docs site |+| User Guide | `pOsGYCXsbNQG` | `docs/User Guide/` (Markdown + `!!!meta.json`) | `apps/server/src/assets/help/help_meta.json` (the tree) + `help_content.json` (each page's HTML, keyed by `_help_<noteId>`); `site/user-guide` on the docs site || Developer Guide | `jdjRLhLV3TtI` | `docs/Developer Guide/` | `site/developer-guide` || Release Notes | `hD3V4hiu2VW4` | `docs/Release Notes/` | the GitHub release body (`scripts/release-notes-body.mts`, `release.yml`) |@@ -16,14 +16,15 @@ headless sync read it.`pnpm edit-docs:edit-docs` (`apps/edit-docs/src/edit-docs.ts`) zips every non-`exportOnly` mapping,imports it into an in-memory database with `preserveIds: true`, opens an Electron window, and — 10 safter any entity change — `rm -rf`s **every** mapping's directory and re-exports it from the-database: Markdown for the three trees, HTML for the User Guide. Nothing exports on close, and an+database as Markdown, then derives the two help artifacts from the User Guide's export (the+`helpMeta` / `helpContent` keys of its mapping). Nothing exports on close, and anuntouched session writes nothing.`pnpm edit-docs:sync-docs` (`apps/edit-docs/src/sync-docs.ts`, `docs.mjs sync`) is the same importand the same export with no window: `apps/edit-docs/src/docs_pipeline.ts` holds the shared code.Running it on a clean tree is byte-stable; running it after a hand edit normalizes the Markdown theway the editor would (the import renders Markdown to HTML, the export turns it back) and regenerates-the HTML and both help metas. ~7 s.+both help artifacts. ~7 s.Consequences:@@ -37,7 +38,7 @@ Consequences:first H1 and demotes a differing one.- `internalLink` / `imageLink` relations are never in the meta — they are rebuilt from content.- `pnpm docs:build` (`apps/build-docs`) is the **site** build: it imports `docs/` again and share-exports- it to `site/`, ignoring `edit-docs-config.yaml`. It is not a way to regenerate `doc_notes`.+ it to `site/`, ignoring `edit-docs-config.yaml`. It is not a way to regenerate the help artifacts.## `!!!meta.json` (formatVersion 2)@@ -67,29 +68,33 @@ attachments, dirFileName, children`. Types: `packages/trilium-core/src/meta.ts`;## What the app reads-- **In-app help** (`F1`, help buttons): `apps/server/src/in_app_help_provider.ts` loads- `doc_notes/en/User Guide/!!!meta.json` — a minified `HiddenSubtreeItem[]` (not a NoteMetaFile)- built by `apps/edit-docs/src/help_meta_generator.ts`: each page becomes `_help_<noteId>` of type- `doc` with `#docName` (`User Guide/User Guide/<folders>/<title>`), `#docUrl` (the alias chain) and- `#iconClass`. `checkHiddenSubtree()` materializes it under `_help`; `doc_renderer.ts` fetches- `doc_notes/en/<docName>.html` and refuses a docName outside `[a-zA-Z0-9_/\- ()&.,\`]`.-- **Standalone/mobile**: `apps/standalone/src/assets/help_meta.json` — the same tree as `webView`- items pointing at `docUrl`; a page without an alias is dropped.+- **In-app help** (`F1`, help buttons): `help_meta.json` is a `HiddenSubtreeItem[]` (not a+ NoteMetaFile) built by `apps/edit-docs/src/help_meta_generator.ts`: each page becomes+ `_help_<noteId>` with its own type, `#docUrl` (the alias chain, absent without a `shareAlias`)+ and `#iconClass`. `help_content.json` (`help_bundle_generator.ts`) maps each ID to its HTML, with+ links rewritten to `#root/_help_<noteId>` and assets to `{{helpAssets}}/<path>`. The pages are+ **virtual notes**: `in_app_help.ts` in core registers a provider that builds the `_help` subtree+ in becca on every load — never stored in the database, never synced, read-only. Server/desktop+ read both files through `apps/server/src/in_app_help_provider.ts`, standalone/mobile through+ `apps/standalone/src/lightweight/in_app_help_provider.ts`. Images stay in `docs/User Guide/`;+ the `in-app-help` skill covers how each platform serves them.- **Help buttons link by noteId** (`<HelpButton helpPage="…">` → `openInAppHelpFromUrl` →`_help_<id>`; `Modal helpPageId`; `services/in_app_help.ts` maps note types, collection views andsidebar sections). ~60 IDs are hard-coded in `apps/client/src`; `docs.mjs show` lists them per pageand `check` fails when one points nowhere. `apps/client/src/services/in_app_help.spec.ts` is the CI- guard for the `in_app_help.ts` maps, the docName files and the `_help_` links inside the HTML.+ guard for the `in_app_help.ts` maps against `help_meta.json`.- **Public URL** = `https://docs.triliumnotes.org` + `/` + each ancestor's `shareAlias` (ancestorswithout one contribute nothing). Unique as a full path, not globally (`troubleshooting` is usedthree times). Hard-coded in `README.md` (mirrored to 40 translated READMEs by CI), `apps/website`,`apps/web-clipper`, the about dialog; `check` resolves every literal against the alias chains.- **Search docs examples**: `packages/trilium-core/src/services/search/docs_examples.spec.ts`requires every query shown in `Navigation/Search.md` and `Quick search.md` to have a test.-- **LLM tools** read the same `doc_notes` files (`apps/server/src/services/llm/tools/doc_notes.ts`).+- **LLM tools** read the `_help` virtual notes through becca and search them with the application's+ own search (`packages/trilium-core/src/services/llm/tools/help_tools.ts`).-`doc_notes/cn/` holds nine legacy hand-written system snippets (launch-bar and hidden-note docs), no-User Guide, and is frozen; the client always requests the User Guide in `en`.+The few hand-written system snippets (launch-bar and hidden-note docs) are not part of the User+Guide: `apps/client/src/services/doc_renderer.ts` renders them from the client catalogue's+`doc_notes` keys, selected by a `#docName` label.## What the site build reads