gaschz/trilium
1
0
Fork 0
mirror of https://github.com/zadam/trilium.git synced 2026-01-01 20:24:25 +01:00
Code Issues Actions 9 Packages Projects Releases Wiki Activity

docs(user): mention icon pack prefix constraints

Browse Source
This commit is contained in:
Elian Doran 2025-12-28 12:36:18 +02:00
parent 13b700e0e5
commit c14d95f561
No known key found for this signature in database
2 changed files with 45 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html generated vendored
View File

@ -1,7 +1,7 @@
<aside class="admonition note">
<p>e This page describes how to create custom icon packs. For a general description
of how to use already existing icon packs, see&nbsp;<a class="reference-link"
href="#root/Wy267RK4M69c/_help_gOKqSJgXLcIj">Icon Packs</a>.</p>
href="#root/_help_gOKqSJgXLcIj">Icon Packs</a>.</p>
</aside>
<h2>Supported formats</h2>
<p>The first step is to analyze if the icon set being packed can be integrated
@ -45,13 +45,13 @@
<h2>Unsupported formats</h2>
<p>Trilium <strong>does not</strong> support the following formats:</p>
<ul>
<li data-list-item-id="e71f13fe82e1cb1db9ef6ff3a9d0c4561">SVG-based fonts.</li>
<li data-list-item-id="ebe2117dbbb6615f59fc824e234500344">Individual SVGs.</li>
<li data-list-item-id="e9ae32c13be797cfc38e1e1ebc9e59e36"><code spellcheck="false">.eot</code> fonts (legacy and proprietary).</li>
<li data-list-item-id="e82a131514827c3594823b95a1e032e55">SVG-based fonts.</li>
<li data-list-item-id="ea255621003bfddf0c27b138800b7461e">Individual SVGs.</li>
<li data-list-item-id="eb75d3b9b71a147f48925903844e878a0"><code spellcheck="false">.eot</code> fonts (legacy and proprietary).</li>
<li
data-list-item-id="e8f2e3426d2894ae6cbdafa64dcf0a8d5">Duotone icons, since it requires a special CSS format that Trilium doesn't
data-list-item-id="e67532d402708b0d266f438de7afc617b">Duotone icons, since it requires a special CSS format that Trilium doesn't
support.</li>
<li data-list-item-id="e7f19affcaed8c29daad535bda899a1ba">Any other font format not specified in the <em>Supported formats</em> section.</li>
<li data-list-item-id="ee56cb0fb0ae77e969c44844a2b56ef94">Any other font format not specified in the <em>Supported formats</em> section.</li>
</ul>
<p>In this case, the font must be manually converted to one of the supported
formats (ideally <code spellcheck="false">.woff2</code>).</p>
@ -59,8 +59,8 @@
<p>In order to create a new icon pack from a set of icons, it must meet the
following criteria:</p>
<ol>
<li data-list-item-id="e7350a058f6e411f11d2423cabf55d3b8">It must have a web font of the supported format (see above).</li>
<li data-list-item-id="e104b6d50d1163808a5e792138c8ed2ae">It must have some kind of list, containing the name of each icon and the
<li data-list-item-id="eba517372b7686baf9c5ffbec386e7853">It must have a web font of the supported format (see above).</li>
<li data-list-item-id="e960457bf372dd1a2e3ec77140b38051c">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 <code spellcheck="false">.css</code> file that can be used to
extract the icon names from.</li>
@ -71,7 +71,7 @@
<h3>Creating the manifest</h3>
<p>This is the most difficult part of creating an icon pack, since it requires
processing of the icon list to match Trilium's format.</p>
<p>The icon pack manifest is a JSON file with the following structure:</p><pre><code class="language-application-json">{
<p>The icon pack manifest is a JSON file with the following structure:</p><pre><code class="language-text-x-trilium-auto">{
"icons": {
"bx-ball": {
"glyph": "\ue9c2",
@ -84,14 +84,14 @@
}
}</code></pre>
<ul>
<li data-list-item-id="eaa96cca5faf255f2d85f3c8a2382e562">The JSON example is a sample from the Boxicons font.</li>
<li data-list-item-id="e5c069d6f00eeb09abafa8f4e5c04dc16">This is simply a mapping between the CSS classes (<code spellcheck="false">bx-ball</code>),
<li data-list-item-id="e421d9a5fbad061cc4bb80123d2b3b383">The JSON example is a sample from the Boxicons font.</li>
<li data-list-item-id="e61b71a1639566cc9ff760a99aca2279a">This is simply a mapping between the CSS classes (<code spellcheck="false">bx-ball</code>),
to its corresponding code point in the font (<code spellcheck="false">\ue9c2</code>)
and the terms/aliases used for search purposes.</li>
<li data-list-item-id="efcb8212a573b12f1fa5b1f8b4432ac81">Note that it's also possible to use the unescaped glyph inside the JSON.
<li data-list-item-id="e7f407f989ab48267d31975f75c89d007">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.</li>
<li
data-list-item-id="e8ffd5edb1164224b0d33cae84f5bacec">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.</li>
</ul>
<p>In order to generate this manifest, generally a script is needed that
@ -163,28 +163,28 @@ console.log(processIconPack("light"));</code></pre>
</aside>
<h3>Creating the icon pack</h3>
<ol>
<li data-list-item-id="e4ca0cda172609e9c59345cb8393d66b2">Create a note of type <em>Code</em>.</li>
<li data-list-item-id="eb986f68ba5608b4b24a0db284dd21f89">Set the language to <em>JSON</em>.</li>
<li data-list-item-id="e3b9e03150b44675880fdc10d97a5c67e">Copy and paste the manifest generated in the previous step as the content
<li data-list-item-id="e7d2cd4845de4760238012fc2ae8dc7a5">Create a note of type <em>Code</em>.</li>
<li data-list-item-id="ef8c38938d0e7f8db06bc1e48654ba3d7">Set the language to <em>JSON</em>.</li>
<li data-list-item-id="eb4d1eeb7b1af1474870e646096d5c71b">Copy and paste the manifest generated in the previous step as the content
of this note.</li>
<li data-list-item-id="e228db1d2b5e53319d9e9284a2a3d9c4a">Go to the <a href="#root/pOsGYCXsbNQG/gh7bpGYxajRS/BFs8mudNFgCS/_help_0vhv7lsOLy82">note attachment</a> and
upload the font file (in <code spellcheck="false">.woff2</code>, <code spellcheck="false">.woff</code>,
<li data-list-item-id="e1e5a73c0ed4c207555912ccae863aa1c">Go to the <a href="#root/_help_0vhv7lsOLy82">note attachment</a> and upload the
font file (in <code spellcheck="false">.woff2</code>, <code spellcheck="false">.woff</code>,
<code
spellcheck="false">.ttf</code>) format.
<ol>
<li data-list-item-id="ebbb9e1be96cd785a587c4feeb83d5b1c">Trilium identifies the font to use from attachments via the MIME type,
<li data-list-item-id="e2aaef242576df43f2c9259ec743593c4">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 <code spellcheck="false">font/woff2</code>).</li>
<li data-list-item-id="e18a84d485caf1fdbedb2f1eff5a5b113">Make sure the <code spellcheck="false">role</code> appears as <code spellcheck="false">file</code>,
<li data-list-item-id="ed7e90b501e2503f559c3af48c3d1ae0c">Make sure the <code spellcheck="false">role</code> appears as <code spellcheck="false">file</code>,
otherwise the font will not be identified.</li>
<li data-list-item-id="e3eac302b56bec68f92e65ec04d3479b4">Multiple attachments are supported, but only one font will actually be
<li data-list-item-id="e7fe120986469e80972cfff7e08095ce3">Multiple attachments are supported, but only one font will actually be
used in Trilium's order of preference: <code spellcheck="false">.woff2</code>,
<code
spellcheck="false">.woff</code>, <code spellcheck="false">.ttf</code>. As such, there's not
much reason to upload more than one font per icon pack.</li>
</ol>
</li>
<li data-list-item-id="e85d0ad86408f5621af022cb93bf9538a">Go back to the note and rename it. The name of the note will also be the
<li data-list-item-id="e07ea13454ff47d3a80d140e435f6e31a">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.</li>
</ol>
<h3>Assigning the prefix</h3>
@ -201,39 +201,45 @@ console.log(processIconPack("light"));</code></pre>
<p>For our example with Phosphor Icons, we can use the <code spellcheck="false">ph</code> prefix
since it also matches the prefix set in the original CSS. So in this case
it would be <code spellcheck="false">#iconPack=ph</code>.</p>
<aside class="admonition important">
<p>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&nbsp;<a class="reference-link" href="#root/pOsGYCXsbNQG/BgmBlOIl72jZ/qzNzp9LYQyPT/_help_bnyigUA2UK7s">Backend (server) logs</a>.</p>
</aside>
<h3>Final steps</h3>
<ul>
<li data-list-item-id="e98981595a95a476c72e23d64017f8bf5"><a href="#root/pOsGYCXsbNQG/BgmBlOIl72jZ/_help_s8alTXmpFR61">Refresh the client</a>
<li data-list-item-id="ea0a195d13028ebcfdd45cd27468bae7d"><a href="#root/_help_s8alTXmpFR61">Refresh the client</a>
<ul>
<li data-list-item-id="e783cdca6a45295c749bdb3f517993b1d">Change the icon of the note and look for the <em>Filter</em> icon in the
<li data-list-item-id="ecfbcbc9a17681cac7e86039dafa42280">Change the icon of the note and look for the <em>Filter</em> icon in the
top-right side.</li>
<li data-list-item-id="e6fe0bd5663842b09fe2275eadc2030fd">Check if the new icon pack is displayed there and click on it to see the
<li data-list-item-id="e37c446c42f22aa5fa6417a2521b4ea3f">Check if the new icon pack is displayed there and click on it to see the
full list of icons.</li>
<li data-list-item-id="e71f0d45c6438b3c0ccbbbdcf3198ad59">Go through most of the items to look for issues such as missing icon,
<li data-list-item-id="e9546ed2a86e5debc1c3146972ce3ae5e">Go through most of the items to look for issues such as missing icon,
wrong names (some icons have aliases/terms that can cause issues).</li>
</ul>
</li>
<li data-list-item-id="e6b44f118674488a1072852fe90e4a05f">Optionally, assign an icon from the new icon pack to this note. This icon
<li data-list-item-id="e6d48f2f0011e6dbbbf2aedce5a63ddd8">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.</li>
<li
data-list-item-id="e01c697d656a553ada696d37bd64c62bf">The icon pack can then be <a href="#root/pOsGYCXsbNQG/gh7bpGYxajRS/_help_mHbBMPDPkVV5">exported as ZIP</a> in
data-list-item-id="e9b5f41994bb6beae98a2d9a1e396fba0">The icon pack can then be <a href="#root/_help_mHbBMPDPkVV5">exported as ZIP</a> in
order to be distributed to other users.
<ul>
<li data-list-item-id="e7951bc9d8f6ef4b1eadb2baa58d2176a">It's important to note that icon packs are considered “unsafe” by default,
<li data-list-item-id="e9a0f122846acf046541a084e505aba81">It's important to note that icon packs are considered “unsafe” by default,
so “Safe mode” must be disabled when importing the ZIP.</li>
<li data-list-item-id="eb2c0cfa4acecd022310b293e5b567587">Consider linking new users to the&nbsp;<a class="reference-link" href="#root/pOsGYCXsbNQG/gh7bpGYxajRS/Wy267RK4M69c/_help_gOKqSJgXLcIj">Icon Packs</a>&nbsp;documentation
<li data-list-item-id="e0e3990178843580147bb801c2c629a25">Consider linking new users to the&nbsp;<a class="reference-link" href="#root/_help_gOKqSJgXLcIj">Icon Packs</a>&nbsp;documentation
in order to understand how to import and use an icon pack.</li>
</ul>
</li>
</ul>
<h3>Troubleshooting</h3>
<p>If the icon pack doesn't show up, look through the&nbsp;<a class="reference-link"
href="#root/pOsGYCXsbNQG/BgmBlOIl72jZ/qzNzp9LYQyPT/_help_bnyigUA2UK7s">Backend (server) logs</a>&nbsp;for
clues.</p>
href="#root/_help_bnyigUA2UK7s">Backend (server) logs</a>&nbsp;for clues.</p>
<ul>
<li data-list-item-id="e96ef68035bc0b412f593a67ada438879">One example is if the font could not be retrieved: <code spellcheck="false">ERROR: Icon pack is missing WOFF/WOFF2/TTF attachment: Boxicons v3 400 (dup) (XRzqDQ67fHEK)</code>.</li>
<li data-list-item-id="ea20b69c8a700cef8919d3c74cb564d4d">One example is if the font could not be retrieved: <code spellcheck="false">ERROR: Icon pack is missing WOFF/WOFF2/TTF attachment: Boxicons v3 400 (dup) (XRzqDQ67fHEK)</code>.</li>
<li
data-list-item-id="e0ea23295c4ddec6fa9fe0bf937ffc01b">Make sure the prefix is unique and not already taken by some other icon
data-list-item-id="ec83897ba2caaeb0d906b29e9e4f52a77">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.</li>
<li data-list-item-id="ed42cfe9240d7ec8626e512f9322bf8b9">Make sure the prefix consists only of alphanumeric characters, hyphens
and underscore.</li>
</ul>

6
docs/User Guide/User Guide/Theme development/Creating an icon pack.md vendored
View File

@ -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 <a class="reference-link" href="../Troubleshooting/Error%20logs/Backend%20(server)%20logs.md">Backend (server) logs</a>.
### 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 <a class="reference-link" href="../Troubleshooting/Error%20logs/Backend%20(server)%20logs.md">Backend (server) logs</a> 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.
* 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.