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): let the docs tooling name an AI provider or import source by its mark
Elian Doranfba15ae3ef22
diff --git a/.claude/skills/writing-documentation/SKILL.md b/.claude/skills/writing-documentation/SKILL.mdindex f2b3ef7d40..00453d1901 100644--- a/.claude/skills/writing-documentation/SKILL.md+++ b/.claude/skills/writing-documentation/SKILL.md@@ -1,6 +1,6 @@---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` 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 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.---# Writing Trilium's documentation@@ -154,6 +154,10 @@ skeletons per page kind are [references/page-templates.md](references/page-templ`apps/client/src/fonts/text-editor-icons.woff2` and`packages/trilium-core/src/services/icon_pack_text_editor.json`. `icons` and `check` both flaga Trilium SVG the font lacks. A Trilium SVG `src/icons/foo.svg` becomes `cke-trilium-foo`.+ An AI provider or an import source is shown by its mark,+ `<span class="tn-icon tn-brand tn-brand-<name>"></span>`, before its name. The `tn-brand` pack+ is built from `apps/icon-pack-builder/brand-icons/<name>.svg` the same way: a new SVG there+ needs `start tn-brand`, committing `brand-icons.woff2` and `icon_pack_brands.json`.9. Callouts: `> [!NOTE]` context/history · `> [!TIP]` a better way · `> [!IMPORTANT]` beta status,requirement, third-party disclaimer · `> [!WARNING]` data/security risk or a version-gated break.10. Version facts: "Since v0.104.0, …", "Starting with v0.104.0, …", "Versions prior to v0.103.0 …".diff --git a/.claude/skills/writing-documentation/docs.mjs b/.claude/skills/writing-documentation/docs.mjsindex 90db2392a2..168538c548 100644--- a/.claude/skills/writing-documentation/docs.mjs+++ b/.claude/skills/writing-documentation/docs.mjs@@ -13,7 +13,7 @@* rename <page> <title> retitle a page (meta + H1); links follow on `sync`* move <page> <parent> [--after s|--first] reparent a page and its files* delete <page> remove a page; refuses when the app links to it- * icons <query...> [--pack bx|cke] search the icon fonts the docs can use+ * 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@@ -53,11 +53,17 @@ const TREES = {const ICON_PACKS = {bx: "packages/trilium-core/src/services/icon_pack_boxicons-v2.json",- cke: "packages/trilium-core/src/services/icon_pack_text_editor.json"+ cke: "packages/trilium-core/src/services/icon_pack_text_editor.json",+ "tn-brand": "packages/trilium-core/src/services/icon_pack_brands.json"};+const ICON_PACK_LABELS = { bx: "app UI, boxicons", cke: "text editor toolbar", "tn-brand": "AI providers and import sources" };const CKE_BUILDER = "apps/icon-pack-builder/src/providers/ckeditor.ts";-const CKE_REBUILD = "run `pnpm --filter @triliumnext/icon-pack-builder start cke` and commit "- + "apps/client/src/fonts/text-editor-icons.woff2 with " + ICON_PACKS.cke;+const BRAND_ICON_DIR = "apps/icon-pack-builder/brand-icons";+/** The packs built from SVGs in the repository, which `staleIconFonts()` compares with their sources. */+const BUILT_ICON_PACKS = {+ cke: { font: "text-editor-icons.woff2", missing: () => staleCkeIcons() },+ "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_/\- ()&.,`]+$/;@@ -370,15 +376,14 @@ function icons() {console.log(problems.length ? `${problems.length} unknown icon class(es)` : "every icon class in the docs exists in a built-in pack");return;}- const stale = packs.includes("cke") ? staleCkeIcons() : [];- if (stale.length) console.log(`! cke font is out of date, no glyph for ${stale.join(", ")}\n ${CKE_REBUILD}\n`);+ for (const problem of staleIconFonts(packs)) console.log(`! ${problem}\n`);const query = flags._.map((q) => q.toLowerCase());- if (!query.length) die("usage: icons <query...> [--pack bx|cke] | icons --check");+ if (!query.length) die("usage: icons <query...> [--pack bx|cke|tn-brand] | icons --check");for (const pack of packs) {const manifest = loadIconPack(pack);const matches = Object.entries(manifest.icons).filter(([name, def]) => query.every((q) => name.includes(q) || (def.terms ?? []).some((t) => t.includes(q))));if (!matches.length) continue;- console.log(`${pack} (${pack === "cke" ? "text editor toolbar" : "app UI, boxicons"}) — ${matches.length} match(es)`);+ console.log(`${pack} (${ICON_PACK_LABELS[pack]}) — ${matches.length} match(es)`);for (const [name] of matches.slice(0, 40)) console.log(` <span class="tn-icon ${pack} ${name}"></span>`);if (matches.length > 40) console.log(` … ${matches.length - 40} more`);}@@ -453,8 +458,7 @@ function check() {checkContent(index, errors, warnings);if (treeName === "user") checkHtmlMirror(index, errors, warnings);}- const stale = staleCkeIcons();- if (stale.length) warnings.push(`cke font is out of date, no glyph for ${stale.join(", ")}: ${CKE_REBUILD}`);+ warnings.push(...staleIconFonts(Object.keys(BUILT_ICON_PACKS)));if (trees.includes("user")) {checkCodeReferences(loadTree("user"), errors);checkUrlLiterals(errors);@@ -882,6 +886,29 @@ function loadIconPack(pack) {return iconCache.get(pack);}+/** A line per built pack among `packs` whose font lacks a glyph for one of its SVGs, with the rebuild command. */+function staleIconFonts(packs) {+ const problems = [];+ for (const pack of packs.filter((p) => p in BUILT_ICON_PACKS)) {+ const { font, missing } = BUILT_ICON_PACKS[pack];+ const stale = missing();+ if (!stale.length) continue;+ problems.push(`${pack} font is out of date, no glyph for ${stale.join(", ")}: run `+ + `\`pnpm --filter @triliumnext/icon-pack-builder start ${pack}\` and commit `+ + `apps/client/src/fonts/${font} with ${ICON_PACKS[pack]}`);+ }+ return problems;+}++/** The `tn-brand-*` classes of the SVGs in `BRAND_ICON_DIR` that the font has no glyph for. */+function staleBrandIcons() {+ const known = loadIconPack("tn-brand").icons;+ return fs.readdirSync(path.join(ROOT, BRAND_ICON_DIR))+ .filter((f) => f.endsWith(".svg"))+ .map((f) => `tn-brand-${f.slice(0, -".svg".length)}`)+ .filter((id) => !(id in known));+}+/*** The `cke-trilium-*` classes of the SVGs in `packages/ckeditor5` that the font has no glyph for.* The folders come from `TRILIUM_ICON_DIRS` in the builder, so the two cannot drift.@@ -903,7 +930,7 @@ function staleCkeIcons() {return stale;}-/** `bx bx-star`, `bx bxs-grid`, `cke cke-quote`, with optional modifiers such as `bx-flip-horizontal`. */+/** `bx bx-star`, `bx bxs-grid`, `cke cke-quote`, `tn-brand tn-brand-openai`, with optional modifiers such as `bx-flip-horizontal`. */function iconExists(cls) {const parts = cls.trim().split(/\s+/);const pack = parts[0];@@ -913,8 +940,8 @@ function iconExists(cls) {}function normalizeIconClass(input) {- const name = input.trim().replace(/^(bx|cke)\s+/, "");- const pack = name.startsWith("cke-") ? "cke" : "bx";+ const name = input.trim().replace(/^(bx|cke|tn-brand)\s+/, "");+ const pack = name.startsWith("cke-") ? "cke" : name.startsWith("tn-brand-") ? "tn-brand" : "bx";return `${pack} ${name}`;}diff --git a/.claude/skills/writing-documentation/references/style-guide.md b/.claude/skills/writing-documentation/references/style-guide.mdindex f994af4165..a878b5fe99 100644--- a/.claude/skills/writing-documentation/references/style-guide.md+++ b/.claude/skills/writing-documentation/references/style-guide.md@@ -145,6 +145,7 @@ A button, menu or toolbar control is named by its icon, never by a cropped scree```html<span class="tn-icon bx bx-history"></span> <!-- app UI: Boxicons v2 --><span class="tn-icon cke cke-three-vertical-dots"></span> <!-- text editor toolbar: Text Editor Icons -->+<span class="tn-icon tn-brand tn-brand-openai"></span> <!-- AI provider or import source: Brand Icons -->```- 106 icons on 36 pages (55 `bx`, 51 `cke`), almost all under Note Types and Basic Concepts. Class is@@ -158,7 +159,8 @@ A button, menu or toolbar control is named by its icon, never by a cropped scree- `cke` (235 glyphs) is the editor's own icon set built into a font (`packages/trilium-core/src/services/icon_pack_text_editor.json`); upstream `IconTableMergeCell` → `cke-table-merge-cell`,Trilium's own SVGs → `cke-trilium-<file>` (`cke-trilium-kbd`, `cke-trilium-ai`). `bx` is- `icon_pack_boxicons-v2.json` (1635). `docs.mjs icons <terms>` searches both; `icons --check`+ `icon_pack_boxicons-v2.json` (1635). `tn-brand` holds the marks of the AI providers and import+ sources (`icon_pack_brands.json`). `docs.mjs icons <terms>` searches all three; `icons --check`validates every class in the docs. `iconClass` in the meta uses `bx` only. The `cke` font isrebuilt by hand, so a new editor button can be missing from it; see rule 8 in `SKILL.md`.