From c14d95f5614512bb75957e84f3fbc00b0e0a5419 Mon Sep 17 00:00:00 2001 From: Elian Doran Date: Sun, 28 Dec 2025 12:36:18 +0200 Subject: [PATCH] docs(user): mention icon pack prefix constraints --- .../Creating an icon pack.html | 74 ++++++++++--------- .../Creating an icon pack.md | 6 +- 2 files changed, 45 insertions(+), 35 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 dc303d918..e3a76c42d 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 @@

Supported formats

The first step is to analyze if the icon set being packed can be integrated @@ -45,13 +45,13 @@

Unsupported formats

Trilium does not support the following formats:

In this case, the font must be manually converted to one of the supported formats (ideally .woff2).

@@ -59,8 +59,8 @@

In order to create a new icon pack from a set of icons, it must meet the following criteria:

    -
  1. It must have a web font of the supported format (see above).
    2. -
  2. It must have some kind of list, containing the name of each icon and the +
  3. It must have a web font of the supported format (see above).
    4. +
  4. 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.
    5. @@ -71,7 +71,7 @@

    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:

    {
+
    The icon pack manifest is a JSON file with the following structure:
    {
 	"icons": {
 		"bx-ball": {
 			"glyph": "\ue9c2",
@@ -84,14 +84,14 @@
 	}
 }
    
 
      
-  
    • The JSON example is a sample from the Boxicons font.
      • 
-  
    • This is simply a mapping between the CSS classes (bx-ball),
+  
    • 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.
+  
    • 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
+  data-list-item-id="ec4b9b5ac1609500d36d35e659d61b61f">The first term is also considered the “name” of the icon, which is displayed
     while hovering over it in the icon selector.
      • 
 
    
 
    In order to generate this manifest, generally a script is needed that
@@ -163,28 +163,28 @@ console.log(processIconPack("light"));

    Creating the icon pack

      -
    1. Create a note of type Code.
      2. -
    2. Set the language to JSON.
      3. -
    3. Copy and paste the manifest generated in the previous step as the content +
    4. Create a note of type Code.
      5. +
    5. Set the language to JSON.
      6. +
    6. Copy and paste the manifest generated in the previous step as the content of this note.
      7. -
    7. Go to the note attachment and - upload the font file (in .woff2, .woff, +
    8. Go to the note attachment and upload the + font file (in .woff2, .woff, .ttf) format.
        -
      1. Trilium identifies the font to use from attachments via the MIME type, +
      2. 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).
        3. -
      3. Make sure the role appears as file, +
      4. Make sure the role appears as file, otherwise the font will not be identified.
        5. -
      5. Multiple attachments are supported, but only one font will actually be +
      6. 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.
      9. -
    9. Go back to the note and rename it. The name of the note will also be the +
    10. 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

    @@ -201,39 +201,45 @@ console.log(processIconPack("light"));

    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">Backend (server) logs for clues.

    \ No newline at end of file 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 427b6595a..218c21b21 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 @@ -155,6 +155,9 @@ 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. + ### Final steps * [Refresh the client](../Troubleshooting/Refreshing%20the%20application.md) @@ -171,4 +174,5 @@ For our example with Phosphor Icons, we can use the `ph` prefix since it also ma 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. \ No newline at end of file +* 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. +* Make sure the prefix consists only of alphanumeric characters, hyphens and underscore. \ No newline at end of file