From 3742cd4a51c26c197dd0603dd646f20174a00678 Mon Sep 17 00:00:00 2001 From: hulmgulm Date: Sun, 8 Feb 2026 10:29:43 +0100 Subject: [PATCH 1/4] doc: enhanced icon pack creation --- .../Themes/Icon Packs.html | 7 +- .../Creating an icon pack.html | 263 ++++++++++-------- .../Developer Guide/Documentation.md | 2 +- docs/User Guide/!!!meta.json | 4 +- .../Creating an icon pack.md | 120 ++++---- 5 files changed, 219 insertions(+), 177 deletions(-) diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Themes/Icon Packs.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Themes/Icon Packs.html index 5d41a23941..fa8837c3ac 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Themes/Icon Packs.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Themes/Icon Packs.html @@ -26,10 +26,9 @@
  • Ideally, create a dedicated spot in your note tree where to place the icon packs.
  • Right click the note where to put it and select Import into note.
    • -
  • Uncheck Safe import.
    • -
  • Select Import.
    • -
  • Refresh the application.
    • +
  • Uncheck Safe import.
    • +
  • Select Import.
    • +
  • Refresh the application.
    • -

    Creating the icon pack

    +

    Assigning the prefix

    +

    Before an icon pack can be used, it needs to have a prefix defined. This + prefix uniquely identifies the icon pack so that it can be used throughout + the application.

    +

    To do so, Trilium makes use of the same format that was used for the internal + icon pack (Boxicons). For example, when an icon from Boxicons is set, it + looks like this: #iconClass="bx bxs-sushi". + In this case, the icon pack prefix is bx and + the icon class name is bxs-sushi.

    +

    In order for an icon pack to be recognized, the prefix must be specified + in the #iconPack label. 

    +

    For our example with Phosphor Icons, we can use the ph prefix + since it also matches the prefix set in the original CSS. So in this case + it would be #iconPack=ph.

    + +

    Creating the Trilium icon pack note

    1. Create a note of type Code.
    2. Set the language to JSON.
      3. +
    3. Rename the note. The name of the note will also be the name of the icon + pack as displayed in the list of icons.
    4. Copy and paste the manifest generated in the previous step as the content of this note.
    5. Go to the note attachment and upload the @@ -181,28 +229,9 @@ console.log(processIconPack("light")); much reason to upload more than one font per icon pack.
    -
  • Go back to the note and rename it. The name of the note will also be the - name of the icon pack as displayed in the list of icons.
    • +
  • Add label: #iconPack=<prefix> (for + Phosphor example: #iconPack=ph).
    • -

    Assigning the prefix

    -

    Before an icon pack can be used, it needs to have a prefix defined. This - prefix uniquely identifies the icon pack so that it can be used throughout - the application.

    -

    To do so, Trilium makes use of the same format that was used for the internal - icon pack (Boxicons). For example, when an icon from Boxicons is set, it - looks like this: #iconClass="bx bxs-sushi". - In this case, the icon pack prefix is bx and - the icon class name is bxs-sushi.

    -

    In order for an icon pack to be recognized, the prefix must be specified - in the #iconPack label. 

    -

    For our example with Phosphor Icons, we can use the ph prefix - since it also matches the prefix set in the original CSS. So in this case - it would be #iconPack=ph.

    -

    Final steps

    Troubleshooting

    If the icon pack doesn't show up, look through the Backend (server) logs for clues.

    + href="#root/_help_bnyigUA2UK7s">[missing note] for clues.

    \ No newline at end of file diff --git a/docs/Developer Guide/Developer Guide/Documentation.md b/docs/Developer Guide/Developer Guide/Documentation.md index 8b43e75bd5..f2f92cc5c2 100644 --- a/docs/Developer Guide/Developer Guide/Documentation.md +++ b/docs/Developer Guide/Developer Guide/Documentation.md @@ -1,5 +1,5 @@ # Documentation -There are multiple types of documentation for Trilium: +There are multiple types of documentation for Trilium: * The _User Guide_ represents the user-facing documentation. This documentation can be browsed by users directly from within Trilium, by pressing F1. * The _Developer's Guide_ represents a set of Markdown documents that present the internals of Trilium, for developers. diff --git a/docs/User Guide/!!!meta.json b/docs/User Guide/!!!meta.json index df7c61602d..8da42b5304 100644 --- a/docs/User Guide/!!!meta.json +++ b/docs/User Guide/!!!meta.json @@ -12290,14 +12290,14 @@ { "type": "relation", "name": "internalLink", - "value": "0vhv7lsOLy82", + "value": "bnyigUA2UK7s", "isInheritable": false, "position": 20 }, { "type": "relation", "name": "internalLink", - "value": "bnyigUA2UK7s", + "value": "0vhv7lsOLy82", "isInheritable": false, "position": 30 }, diff --git a/docs/User Guide/User Guide/Theme development/Creating an icon pack.md b/docs/User Guide/User Guide/Theme development/Creating an icon pack.md index 20bc897899..c9034bd7c0 100644 --- a/docs/User Guide/User Guide/Theme development/Creating an icon pack.md +++ b/docs/User Guide/User Guide/Theme development/Creating an icon pack.md @@ -1,8 +1,20 @@ # Creating an icon pack > [!NOTE] -> This page describes how to create custom icon packs. For a general description of how to use already existing icon packs, see Icon Packs. +> This page explains, step‑by‑step, how to create a create a custom icon pack. For a general description of how to use already existing icon packs, see [missing note]. -## Supported formats +First read the quick flow to get the overall steps. After that there is a concrete example (Phosphor) with a small Node.js script you can run to generate the manifest. + +## Quick flow (what you need to do) + +1. Verify the icon set is a font (one of: .woff2, .woff, .ttf). +2. Obtain a list that maps icon names to Unicode code points (often provided as a JSON like `selection.json` or a CSS file). +3. Create a manifest JSON that maps icon ids to glyphs and search terms. +4. Create a Trilium note of type Code, set language to JSON, paste the manifest as the note content. +5. Upload the font file as an attachment to the same note (MIME type must be `font/woff2`, `font/woff`, or `font/ttf` and role `file`). +6. Add the label `#iconPack=` to the note (prefix: alphanumeric, hyphen, underscore only). +7. Refresh the client and verify the icon pack appears in the icon selector. + +## Verify the icon set The first step is to analyze if the icon set being packed can be integrated into Trilium. @@ -14,8 +26,6 @@ Trilium only supports **font-based icon sets**, with the following formats: | `.woff` | `font/woff` | Higher compatibility, but the font file is bigger. | | `.ttf` | `font/ttf` | Most common, but highest font size. | -## Unsupported formats - Trilium **does not** support the following formats: * SVG-based fonts. @@ -26,46 +36,42 @@ Trilium **does not** support the following formats: In this case, the font must be manually converted to one of the supported formats (ideally `.woff2`). -## Prerequisites +## Manifest format -In order to create a new icon pack from a set of icons, it must meet the following criteria: +The manifest is a JSON object with an `icons` map. Each entry key is the CSS/class id you will use (Trilium uses the CSS class when rendering). Value object: -1. It must have a web font of the supported format (see above). -2. It must have some kind of list, containing the name of each icon and the corresponding Unicode code point. If this is missing, icon fonts usually ship with a `.css` file that can be used to extract the icon names from. +* glyph: the single character (the glyph) — can be the escaped Unicode (e.g. "\\ue9c2") or the literal character. +* terms: array of search aliases; the first term is used as display name in the selector. -## Step-by-step process +Example minimal manifest: -As an example throughout this page, we are going to go through the steps of integrating [Phosphor Icons](https://phosphoricons.com/). - -### Creating the manifest - -This is the most difficult part of creating an icon pack, since it requires processing of the icon list to match Trilium's format. - -The icon pack manifest is a JSON file with the following structure: - -```json +``` { - "icons": { - "bx-ball": { - "glyph": "\ue9c2", - "terms": [ "ball" ] - }, - "bxs-party": { - "glyph": "\uec92", - "terms": [ "party" ] - } - } + "icons": { + "ph-acorn": { + "glyph": "\uea3f", + "terms": ["acorn", "nut"] + }, + "ph-book": { + "glyph": "\uea40", + "terms": ["book", "read"] + } + } } ``` -* The JSON example is a sample from the Boxicons font. -* This is simply a mapping between the CSS classes (`bx-ball`), to its corresponding code point in the font (`\ue9c2`) and the terms/aliases used for search purposes. -* Note that it's also possible to use the unescaped glyph inside the JSON. It will appear strange (e.g. ), but it will be rendered properly regardless. -* The first term is also considered the “name” of the icon, which is displayed while hovering over it in the icon selector. +> [!NOTE] +> * You can supply glyph as the escaped `\uXXXX` sequence or as the actual UTF‑8 character. +> * It is also possible to use the unescaped glyph inside the JSON. It will appear strange (e.g. ), but it will be rendered properly regardless. +> * The manifest keys (e.g. `ph-acorn`) should match the class names used by the font (prefix + name is a common pattern). -In order to generate this manifest, generally a script is needed that processes an already existing list. In the case of Phosphor Icons, the icon list comes in a file called `selection.json` with the following format: +## Concrete example: Phosphor Icons -```json +[Phosphor Icons](https://phosphoricons.com/) provide a `selection.json` that includes `properties.code` (the codepoint) and `properties.name` (the icon name). The goal: convert that into Trilium's manifest. + +Sample `selection.json` excerpt: + +``` { "icons": [ { @@ -95,11 +101,11 @@ In order to generate this manifest, generally a script is needed that processes } ``` -As such, we can write a Node.js script to automatically process the manifest file: +A tiny Node.js script to produce the manifest (place `selection.json` in the same directory and run with Node 20+): ```javascript import { join } from "node:path"; -import { readFileSync } from "node:fs"; +import { readFileSync, writeFileSync } from "node:fs"; function processIconPack(packName) { const path = join(packName); @@ -119,14 +125,19 @@ function processIconPack(packName) { }; } - return JSON.stringify({ - icons - }, null, 2); + writeFileSync("manifest.json", JSON.stringify(icons, null, 2), "utf8"); + console.log("manifest.json created"); } -console.log(processIconPack("light")); +processIconPack("light"); ``` +What to do with the script: + +* Put `selection.json` and `build-manifest.js` in a folder. +* Run: node build-manifest.js +* The script writes `manifest.json` — open it, verify contents, then copy into a Trilium Code note (language: JSON). + > [!TIP] > **Mind the escape format when processing CSS** > @@ -134,17 +145,6 @@ console.log(processIconPack("light")); > > As a more compact alternative, provide the un-escaped character directly, as UTF-8 is supported. -### Creating the icon pack - -1. Create a note of type _Code_. -2. Set the language to _JSON_. -3. Copy and paste the manifest generated in the previous step as the content of this note. -4. Go to the [note attachment](../Basic%20Concepts%20and%20Features/Notes/Attachments.md) and upload the font file (in `.woff2`, `.woff`, `.ttf`) format. - 1. Trilium identifies the font to use from attachments via the MIME type, make sure the MIME type is displayed correctly after uploading the attachment (for example `font/woff2`). - 2. Make sure the `role` appears as `file`, otherwise the font will not be identified. - 3. Multiple attachments are supported, but only one font will actually be used in Trilium's order of preference: `.woff2`, `.woff`, `.ttf`. As such, there's not much reason to upload more than one font per icon pack. -5. Go back to the note and rename it. The name of the note will also be the name of the icon pack as displayed in the list of icons. - ### Assigning the prefix Before an icon pack can be used, it needs to have a prefix defined. This prefix uniquely identifies the icon pack so that it can be used throughout the application. @@ -156,7 +156,19 @@ In order for an icon pack to be recognized, the prefix must be specified in the For our example with Phosphor Icons, we can use the `ph` prefix since it also matches the prefix set in the original CSS. So in this case it would be `#iconPack=ph`. > [!IMPORTANT] -> The prefix must consist of only alphanumeric characters, hyphens and underscore. If the prefix doesn't match these constraints, the icon pack will be ignored and an error will be logged in Backend (server) logs. +> The prefix must consist of only alphanumeric characters, hyphens and underscore. If the prefix doesn't match these constraints, the icon pack will be ignored and an error will be logged in [missing note]. + +## Creating the Trilium icon pack note + +1. Create a note of type _Code_. +2. Set the language to _JSON_. +3. Rename the note. The name of the note will also be the name of the icon pack as displayed in the list of icons. +4. Copy and paste the manifest generated in the previous step as the content of this note. +5. Go to the [note attachment](../Basic%20Concepts%20and%20Features/Notes/Attachments.md) and upload the font file (in `.woff2`, `.woff`, `.ttf`) format. + 1. Trilium identifies the font to use from attachments via the MIME type, make sure the MIME type is displayed correctly after uploading the attachment (for example `font/woff2`). + 2. Make sure the `role` appears as `file`, otherwise the font will not be identified. + 3. Multiple attachments are supported, but only one font will actually be used in Trilium's order of preference: `.woff2`, `.woff`, `.ttf`. As such, there's not much reason to upload more than one font per icon pack. +6. Add label: `#iconPack=` (for Phosphor example: `#iconPack=ph`). ### Final steps @@ -167,11 +179,11 @@ For our example with Phosphor Icons, we can use the `ph` prefix since it also ma * Optionally, assign an icon from the new icon pack to this note. This icon will be used in the icon pack filter for a visual distinction. * The icon pack can then be [exported as ZIP](../Basic%20Concepts%20and%20Features/Import%20%26%20Export.md) in order to be distributed to other users. * It's important to note that icon packs are considered “unsafe” by default, so “Safe mode” must be disabled when importing the ZIP. - * Consider linking new users to the Icon Packs documentation in order to understand how to import and use an icon pack. + * Consider linking new users to the [missing note] documentation in order to understand how to import and use an icon pack. ### Troubleshooting -If the icon pack doesn't show up, look through the Backend (server) logs for clues. +If the icon pack doesn't show up, look through the [missing note] for clues. * One example is if the font could not be retrieved: `ERROR: Icon pack is missing WOFF/WOFF2/TTF attachment: Boxicons v3 400 (dup) (XRzqDQ67fHEK)`. * Make sure the prefix is unique and not already taken by some other icon pack. When there are two icon packs with the same prefix, only one is used. The server logs will indicate if this situation occurs. From 34d691341bd4c8e60a2652f08ee721bbb09fc4f4 Mon Sep 17 00:00:00 2001 From: hulmgulm Date: Sun, 8 Feb 2026 10:41:57 +0100 Subject: [PATCH 2/4] Fixed export --- .../Theme development/Creating an icon pack.html | 8 ++++---- docs/Developer Guide/Developer Guide/Documentation.md | 2 +- .../User Guide/Theme development/Creating an icon pack.md | 8 ++++---- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html index 14c9e94a03..dc27d6050f 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html @@ -1,7 +1,7 @@

    First read the quick flow to get the overall steps. After that there is a concrete example (Phosphor) with a small Node.js script you can run to @@ -202,7 +202,7 @@ processIconPack("light");

    Creating the Trilium icon pack note

      @@ -252,14 +252,14 @@ processIconPack("light");
      • It's important to note that icon packs are considered “unsafe” by default, so “Safe mode” must be disabled when importing the ZIP.
        • -
      • Consider linking new users to the [missing note] documentation +
      • Consider linking new users to the Icon Packs documentation in order to understand how to import and use an icon pack.

      Troubleshooting

      If the icon pack doesn't show up, look through the [missing note] for clues.

      + href="#root/_help_bnyigUA2UK7s">Backend (server) logs for clues.

      • One example is if the font could not be retrieved: ERROR: Icon pack is missing WOFF/WOFF2/TTF attachment: Boxicons v3 400 (dup) (XRzqDQ67fHEK).
      • +There are multiple types of documentation for Trilium: * The _User Guide_ represents the user-facing documentation. This documentation can be browsed by users directly from within Trilium, by pressing F1. * The _Developer's Guide_ represents a set of Markdown documents that present the internals of Trilium, for developers. diff --git a/docs/User Guide/User Guide/Theme development/Creating an icon pack.md b/docs/User Guide/User Guide/Theme development/Creating an icon pack.md index c9034bd7c0..6adc6f9868 100644 --- a/docs/User Guide/User Guide/Theme development/Creating an icon pack.md +++ b/docs/User Guide/User Guide/Theme development/Creating an icon pack.md @@ -1,6 +1,6 @@ # Creating an icon pack > [!NOTE] -> This page explains, step‑by‑step, how to create a create a custom icon pack. For a general description of how to use already existing icon packs, see [missing note]. +> This page explains, step‑by‑step, how to create a create a custom icon pack. For a general description of how to use already existing icon packs, see Icon Packs. First read the quick flow to get the overall steps. After that there is a concrete example (Phosphor) with a small Node.js script you can run to generate the manifest. @@ -156,7 +156,7 @@ In order for an icon pack to be recognized, the prefix must be specified in the For our example with Phosphor Icons, we can use the `ph` prefix since it also matches the prefix set in the original CSS. So in this case it would be `#iconPack=ph`. > [!IMPORTANT] -> The prefix must consist of only alphanumeric characters, hyphens and underscore. If the prefix doesn't match these constraints, the icon pack will be ignored and an error will be logged in [missing note]. +> The prefix must consist of only alphanumeric characters, hyphens and underscore. If the prefix doesn't match these constraints, the icon pack will be ignored and an error will be logged in Backend (server) logs. ## Creating the Trilium icon pack note @@ -179,11 +179,11 @@ For our example with Phosphor Icons, we can use the `ph` prefix since it also ma * Optionally, assign an icon from the new icon pack to this note. This icon will be used in the icon pack filter for a visual distinction. * The icon pack can then be [exported as ZIP](../Basic%20Concepts%20and%20Features/Import%20%26%20Export.md) in order to be distributed to other users. * It's important to note that icon packs are considered “unsafe” by default, so “Safe mode” must be disabled when importing the ZIP. - * Consider linking new users to the [missing note] documentation in order to understand how to import and use an icon pack. + * Consider linking new users to the Icon Packs documentation in order to understand how to import and use an icon pack. ### Troubleshooting -If the icon pack doesn't show up, look through the [missing note] for clues. +If the icon pack doesn't show up, look through the Backend (server) logs for clues. * One example is if the font could not be retrieved: `ERROR: Icon pack is missing WOFF/WOFF2/TTF attachment: Boxicons v3 400 (dup) (XRzqDQ67fHEK)`. * Make sure the prefix is unique and not already taken by some other icon pack. When there are two icon packs with the same prefix, only one is used. The server logs will indicate if this situation occurs. From 0c552eb0c094685af765915b7f3bb654bb5b45e9 Mon Sep 17 00:00:00 2001 From: hulmgulm Date: Sun, 8 Feb 2026 10:45:48 +0100 Subject: [PATCH 3/4] Update apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- .../User Guide/Theme development/Creating an icon pack.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html index dc27d6050f..301602420c 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html @@ -1,5 +1,5 @@ From 639b81b2282c82d1c0f062958cbf78a942c257fc Mon Sep 17 00:00:00 2001 From: hulmgulm Date: Sun, 8 Feb 2026 10:46:02 +0100 Subject: [PATCH 4/4] Update docs/User Guide/User Guide/Theme development/Creating an icon pack.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- .../User Guide/Theme development/Creating an icon pack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/User Guide/User Guide/Theme development/Creating an icon pack.md b/docs/User Guide/User Guide/Theme development/Creating an icon pack.md index 6adc6f9868..5b18610b72 100644 --- a/docs/User Guide/User Guide/Theme development/Creating an icon pack.md +++ b/docs/User Guide/User Guide/Theme development/Creating an icon pack.md @@ -1,6 +1,6 @@ # Creating an icon pack > [!NOTE] -> This page explains, step‑by‑step, how to create a create a custom icon pack. For a general description of how to use already existing icon packs, see Icon Packs. +> This page explains, step‑by‑step, how to create a custom icon pack. For a general description of how to use already existing icon packs, see Icon Packs. First read the quick flow to get the overall steps. After that there is a concrete example (Phosphor) with a small Node.js script you can run to generate the manifest.