Skip to content

Build your personal knowledge base with Trilium Notes

docs(skills): teach the CKEditor skills about the cke icon pack

Elian Doran61a37f22e1c9
diff --git a/.claude/skills/ckeditor5-plugin-development/SKILL.md b/.claude/skills/ckeditor5-plugin-development/SKILL.md
index 9cc43c87bc..476199faf8 100644
--- a/.claude/skills/ckeditor5-plugin-development/SKILL.md
+++ b/.claude/skills/ckeditor5-plugin-development/SKILL.md
@@ -153,8 +153,12 @@ Key rules (inherited from the upstream conventions via `eslint-config-ckeditor5`
`'name'` is added to Trilium's toolbar config (`apps/client/.../text/toolbar.ts`).
- Make features self-configuring: pre-configure the schema and provide config defaults via
`editor.config.define( 'feature', { … } )`, read with `editor.config.get( 'feature.key' )`.
-- SVG icons are imported with `?raw` (`import fooIcon from '../theme/icons/foo.svg?raw';`) and
- surfaced through `export const icons = { fooIcon }` in `index.ts`.
+- SVG icons are imported with `?raw` straight into the file that uses them
+ (`import fooIcon from '../../icons/foo.svg?raw';`); there is no `icons` export any more.
+- Every editor icon, CKEditor's and ours, is also a glyph in the built-in `cke` icon font that the
+ User Guide uses to name toolbar buttons (`cke-table-merge-cell`, `cke-trilium-kbd`). Adding,
+ renaming or removing an SVG, or bumping `ckeditor5`, means regenerating that font and checking
+ the docs for the old class. See "The `cke` icon pack" in `references/ui-and-localization.md`.
## Minimal end-to-end example (inline text attribute)
diff --git a/.claude/skills/ckeditor5-plugin-development/references/review-checklist.md b/.claude/skills/ckeditor5-plugin-development/references/review-checklist.md
index 30dfeb269f..23c351ffa0 100644
--- a/.claude/skills/ckeditor5-plugin-development/references/review-checklist.md
+++ b/.claude/skills/ckeditor5-plugin-development/references/review-checklist.md
@@ -98,8 +98,8 @@ integration items at the end are specific to this monorepo.
carry the CKSource header, some don't; don't add/strip wholesale).
- [ ] **`pluginName` / `requires`** declared `as const`; type augmentation done via
`declare module 'ckeditor5'` (config + command/plugin maps).
-- [ ] Custom SVG icons imported with `?raw` and re-exported via `export const icons = { … }`
- from `index.ts`.
+- [ ] Custom SVG icons live in `packages/ckeditor5/src/icons/` and are imported with `?raw` by
+ the file that uses them.
- [ ] Listeners use `this.listenTo()` (auto-cleaned); any other resources cleaned in `destroy()`.
- [ ] `ckeditor5-metadata.json` updated for new public plugins/UI/HTML output.
- [ ] Model is the source of truth — no view hacks standing in for model state (except genuine
@@ -117,5 +117,9 @@ integration items at the end are specific to this monorepo.
`ClassicEditor` (Decoupled), `PopupEditor` (Balloon + `BlockToolbar`).
- [ ] Block widgets enforce structural invariants with `registerPostFixer` (admonition,
collapsible) rather than relying on command-side cleanup.
+- [ ] An added, renamed, redrawn or removed SVG icon (or a `ckeditor5` bump) comes with a
+ regenerated `cke` pack (`text-editor-icons.woff2` + `icon_pack_text_editor.json`), and no
+ page in `docs/User Guide` still uses a removed `cke-*` class. See `ui-and-localization.md`,
+ "The `cke` icon pack".
- [ ] **Tests use the right environment**: happy-dom for unit/model logic; Playwright
(browser) only where real DOM/layout is required.
diff --git a/.claude/skills/ckeditor5-plugin-development/references/ui-and-localization.md b/.claude/skills/ckeditor5-plugin-development/references/ui-and-localization.md
index 7b74c54f71..2c87e03746 100644
--- a/.claude/skills/ckeditor5-plugin-development/references/ui-and-localization.md
+++ b/.claude/skills/ckeditor5-plugin-development/references/ui-and-localization.md
@@ -157,6 +157,41 @@ button.set( { icon: admonitionIcon } ); // the raw SVG string
`icon` accepts the full SVG XML string. For a recolorable icon, strip `fill`/`stroke`
attributes from the SVG so it inherits `currentColor`.
+### The `cke` icon pack (the User Guide's toolbar icons)
+
+Every editor icon also ships as a glyph in **Text Editor Icons**, a built-in icon font with prefix
+`cke`. The User Guide uses it to name a toolbar button in running text
+(`<span class="tn-icon cke cke-table-merge-cell"></span>`) instead of embedding a screenshot of
+the button. The pack is **internal**: its CSS goes out wherever Boxicons' does (app, in-app help,
+shares, exports, the docs site), but `generateIconRegistry()` lists it only when `isDev()`. So
+only `edit-docs` offers it in the icon picker; users never see it, and the LLM icon search skips
+it.
+
+- **Class names.** An upstream export `IconTableMergeCell` becomes `cke-table-merge-cell`. A
+ Trilium SVG becomes `cke-trilium-<file name>` (`src/icons/kbd.svg` → `cke-trilium-kbd`;
+ `trilium.svg` → `cke-trilium`), a namespace of its own because some names clash with upstream
+ (`copy`).
+- **Where the SVGs are read from.** All of `@ckeditor/ckeditor5-icons`, plus the folders listed in
+ `TRILIUM_ICON_DIRS` in `apps/icon-pack-builder/src/providers/ckeditor.ts` (`src/icons`, and the
+ `theme/icons` folders of `ai_assistant` and `snippets`). An icon kept anywhere else is not in the
+ pack until its folder is added to that list.
+- **Regenerate after any change.** Adding, renaming, redrawing or removing an SVG, or bumping
+ `ckeditor5`, calls for `pnpm --filter @triliumnext/icon-pack-builder start cke`. It writes
+ `apps/client/src/fonts/text-editor-icons.woff2` and
+ `packages/trilium-core/src/services/icon_pack_text_editor.json`; commit both. Also bump the
+ builder's own `@ckeditor/ckeditor5-icons` pin to the new `ckeditor5` version, because the pack is
+ built from that package.
+- **Renaming or removing an icon breaks the docs.** Grep `docs/User Guide` for the old
+ `cke-<name>` class and update those pages through `pnpm edit-docs:edit-docs`, or they render an
+ empty span.
+- **What survives the conversion to a font.** A glyph has one color. Parts drawn at reduced
+ `opacity` become solid (the table and image-alignment icons lose their two-tone contrast), and an
+ icon built from explicit colors can collapse into a blob (`template-generic` becomes a solid
+ square). Fills (either fill rule), strokes and `transform`s convert faithfully. `<text>` is
+ outlined in Arimo's Latin subset; an icon whose text needs another script is skipped with a
+ warning (`list-style-arabic-indic`). For a new icon, draw filled or stroked
+ paths in `currentColor`, and prefer paths over `<text>`.
+
## Dropdowns
Use `createDropdown` + the appropriate `add…ToDropdown` helper; don't compose from scratch
diff --git a/.claude/skills/ckeditor5-reviewing/references/defect-patterns.md b/.claude/skills/ckeditor5-reviewing/references/defect-patterns.md
index c0336c7d8c..77f9d53cb8 100644
--- a/.claude/skills/ckeditor5-reviewing/references/defect-patterns.md
+++ b/.claude/skills/ckeditor5-reviewing/references/defect-patterns.md
@@ -289,6 +289,19 @@ nothing loads it, no button shows, or lint/license/localization is off.
- Fix: add (or don't) as above; `pnpm --filter client exec vitest run src/services/i18n.spec.ts`
checks both directions. (See the Localization group above.)
+**Editor icon changed without regenerating the `cke` icon pack.**
+- Spot: an SVG added, renamed, redrawn or deleted under `packages/ckeditor5/src/icons/` (or a
+ plugin's `theme/icons/`), or a `ckeditor5` version bump, with no matching change to
+ `apps/client/src/fonts/text-editor-icons.woff2` and
+ `packages/trilium-core/src/services/icon_pack_text_editor.json`. Also: an icon placed in a folder
+ that `TRILIUM_ICON_DIRS` in `apps/icon-pack-builder/src/providers/ckeditor.ts` does not list.
+- Why: the User Guide names toolbar buttons with that built-in font
+ (`<span class="tn-icon cke cke-…">`). A stale font shows the old glyph, and a removed or renamed
+ icon leaves every page that used its class with an empty span, in the in-app help and on the
+ docs site. Nothing fails: the docs build only checks that pages exist.
+- Fix: `pnpm --filter @triliumnext/icon-pack-builder start cke`, commit both outputs, and grep
+ `docs/User Guide` for the old `cke-<name>` class. (Minor; Major if docs lose icons.)
+
**Test written against the wrong DOM assumptions.**
- Spot: a synthetic event dispatched without `cancelable: true` whose `preventDefault()` is then
expected to suppress native behaviour; an assertion made immediately after an event the browser