Skip to content

Build your personal knowledge base with Trilium Notes

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.md
index 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 flag
a 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.mjs
index 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.md
index 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 is
rebuilt by hand, so a new editor button can be missing from it; see rule 8 in `SKILL.md`.