Skip to content

Build your personal knowledge base with Trilium Notes

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.md
index 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 documentation
Trilium's User Guide is a tree of Trilium notes, exported to Markdown under `docs/User Guide/` and
described 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 # sca
node $D image timeline shot.png # register a screenshot; prints the <figure> to paste
node $D icons quote --pack cke # icon classes for a toolbar button / app control
node $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 headless
node $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 the
component, 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, an
alias 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 template
icon 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: `<HelpButton
helpPage="<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 app
diff --git a/.claude/skills/writing-documentation/docs.mjs b/.claude/skills/writing-documentation/docs.mjs
index 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 → files
if (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 &nbsp; 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.md
index 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 s
after 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 an
untouched session writes nothing.
`pnpm edit-docs:sync-docs` (`apps/edit-docs/src/sync-docs.ts`, `docs.mjs sync`) is the same import
and 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 the
way 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 and
sidebar sections). ~60 IDs are hard-coded in `apps/client/src`; `docs.mjs show` lists them per page
and `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` (ancestors
without one contribute nothing). Unique as a full path, not globally (`troubleshooting` is used
three 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