mirror of
https://github.com/zadam/trilium.git
synced 2025-12-28 18:24:27 +01:00
docs(user): document icon packs
This commit is contained in:
Elian Doran
parent
1570ea77d8
commit
d834cd78a7
2
apps/server/src/assets/doc_notes/en/User Guide/!!!meta.json
generated
vendored
2
apps/server/src/assets/doc_notes/en/User Guide/!!!meta.json
generated
vendored
File diff suppressed because one or more lines are too long
@ -10,11 +10,13 @@
|
||||
<p>Trilium supports custom user themes, allowing you to personalize the application's
|
||||
appearance. To create a custom theme, follow these steps:</p>
|
||||
<ol>
|
||||
<li><strong>Create a CSS Code Note</strong>: Start by creating a new <a href="#root/_help_6f9hih2hXXZk">code note</a> with
|
||||
the <code>CSS</code> type.</li>
|
||||
<li><strong>Annotate with</strong> <code>#appTheme</code>: Add the <a href="#root/_help_zEY4DaJG4YT5">attribute</a> <code>#appTheme=my-theme-name</code> to
|
||||
your note, where <code>my-theme-name</code> is the name of your custom theme.</li>
|
||||
<li><strong>Define Your Styles</strong>: Write your custom CSS within the
|
||||
<li data-list-item-id="eca8bbfc636daa344eaabbbb94ea94c3f"><strong>Create a CSS Code Note</strong>: Start by creating a new <a href="#root/_help_6f9hih2hXXZk">code note</a> with
|
||||
the <code spellcheck="false">CSS</code> type.</li>
|
||||
<li data-list-item-id="e5ae35a0ee455e32c200fc095bf8415ac"><strong>Annotate with</strong> <code spellcheck="false">#appTheme</code>:
|
||||
Add the <a href="#root/_help_zEY4DaJG4YT5">attribute</a> <code spellcheck="false">#appTheme=my-theme-name</code> to
|
||||
your note, where <code spellcheck="false">my-theme-name</code> is the name
|
||||
of your custom theme.</li>
|
||||
<li data-list-item-id="e7cd8c79dcf2d9edc2d03c924b9d954e1"><strong>Define Your Styles</strong>: Write your custom CSS within the
|
||||
note. Below is an example of a custom theme:</li>
|
||||
</ol><pre><code class="language-text-x-trilium-auto">@font-face {
|
||||
font-family: 'Raleway';
|
||||
@ -72,18 +74,20 @@ body .CodeMirror {
|
||||
<h3>Activating Your Custom Theme</h3>
|
||||
<p>Once you've created your custom theme:</p>
|
||||
<ol>
|
||||
<li>Go to "Menu" -> "Options" -> "Appearance."</li>
|
||||
<li>In the theme selection dropdown, you should see your custom theme listed
|
||||
under the name you provided with the <code>#appTheme</code> <a href="#root/_help_zEY4DaJG4YT5">label</a>.</li>
|
||||
<li>Select your custom theme to activate it.</li>
|
||||
<li data-list-item-id="ee141db479e6972f78a12a2ece4be4d8f">Go to "Menu" -> "Options" -> "Appearance."</li>
|
||||
<li data-list-item-id="e36a48638934829faceb5b68dececd6c7">In the theme selection dropdown, you should see your custom theme listed
|
||||
under the name you provided with the <code spellcheck="false">#appTheme</code>
|
||||
<a
|
||||
href="#root/_help_zEY4DaJG4YT5">label</a>.</li>
|
||||
<li data-list-item-id="eb7987a455a323d619c83e04a3f660cf9">Select your custom theme to activate it.</li>
|
||||
</ol>
|
||||
<p>If you make changes to your theme, press <kbd>Ctrl</kbd> + <kbd>R</kbd> to
|
||||
reload the frontend and apply your updates.</p>
|
||||
<h3>Sharing and Importing Themes</h3>
|
||||
<p>Custom themes can be exported as <code>.tar</code> archives, which can be
|
||||
shared with other users. However, be cautious when importing themes from
|
||||
untrusted sources, as they may contain executable scripts that could pose
|
||||
security risks.</p>
|
||||
<p>Custom themes can be exported as <code spellcheck="false">.tar</code> archives,
|
||||
which can be shared with other users. However, be cautious when importing
|
||||
themes from untrusted sources, as they may contain executable scripts that
|
||||
could pose security risks.</p>
|
||||
<p>An example user theme, <em>Steel Blue</em>, is available in the demo document.</p>
|
||||
<p>
|
||||
<img src="Themes_steel-blue.png" alt="Steel Blue Theme">
|
||||
@ -96,17 +100,19 @@ body .CodeMirror {
|
||||
<h3>Applying Custom CSS</h3>
|
||||
<p>To use custom CSS:</p>
|
||||
<ol>
|
||||
<li><strong>Create a CSS Code Note</strong>: Create a new <a class="reference-link"
|
||||
href="#root/_help_6f9hih2hXXZk">Code</a> note with the <code>CSS</code> type.</li>
|
||||
<li><strong>Add the</strong> <code>appCss</code> <strong>Label</strong>: Annotate
|
||||
the note with the <code>#appCss</code> <a href="#root/_help_zEY4DaJG4YT5">label</a>.</li>
|
||||
<li><strong>Write Your CSS</strong>: Add your custom CSS rules to the note.</li>
|
||||
<li data-list-item-id="e34f8b4bcba7c20fb1b7653fe36ded3da"><strong>Create a CSS Code Note</strong>: Create a new <a class="reference-link"
|
||||
href="#root/_help_6f9hih2hXXZk">Code</a> note with the <code spellcheck="false">CSS</code> type.</li>
|
||||
<li
|
||||
data-list-item-id="ec697ca6baf249b374caa04b0817a54f0"><strong>Add the</strong> <code spellcheck="false">appCss</code> <strong>Label</strong>:
|
||||
Annotate the note with the <code spellcheck="false">#appCss</code> <a href="#root/_help_zEY4DaJG4YT5">label</a>.</li>
|
||||
<li
|
||||
data-list-item-id="e33d95fa67b19ef88f2561c3addecade8"><strong>Write Your CSS</strong>: Add your custom CSS rules to the note.</li>
|
||||
</ol>
|
||||
<p>For example:</p><pre><code class="language-text-x-trilium-auto">/* Custom CSS to style specific elements */
|
||||
.tree-item {
|
||||
color: #ff6347; /* Change tree item color */
|
||||
}</code></pre>
|
||||
<p>When Trilium's frontend starts, all notes labeled with <code>appCss</code> are
|
||||
<p>When Trilium's frontend starts, all notes labeled with <code spellcheck="false">appCss</code> are
|
||||
automatically included in the style element of the HTML page.</p>
|
||||
<p>After making changes, press <kbd>Ctrl</kbd> + <kbd>R</kbd> to reload the frontend
|
||||
and apply your new styles.</p>
|
||||
@ -116,22 +122,24 @@ body .CodeMirror {
|
||||
<h3>Styling Specific Notes in the Tree</h3>
|
||||
<p>To apply specific styles to certain notes in the tree:</p>
|
||||
<ul>
|
||||
<li><strong>Use the</strong> <code>cssClass</code> <strong>Attribute</strong>:
|
||||
Add the <code>cssClass</code> <a href="#root/_help_zEY4DaJG4YT5">attribute</a> to
|
||||
<li data-list-item-id="e885cbe8b8c440d4bf71c95d5f8c73340"><strong>Use the</strong> <code spellcheck="false">cssClass</code> <strong>Attribute</strong>:
|
||||
Add the <code spellcheck="false">cssClass</code> <a href="#root/_help_zEY4DaJG4YT5">attribute</a> to
|
||||
a note, and assign it a value representing the desired CSS class.</li>
|
||||
<li><strong>Define an</strong> <code>iconClass</code>: You can also define
|
||||
a custom icon for a note using the <code>iconClass</code> attribute, selecting
|
||||
from <a href="https://boxicons.com">Box Icons</a> or your own custom classes.</li>
|
||||
<li
|
||||
data-list-item-id="e168c9c99d3bf9e7af0d0bd03ee6903f5"><strong>Define an</strong> <code spellcheck="false">iconClass</code>: You
|
||||
can also define a custom icon for a note using the <code spellcheck="false">iconClass</code> attribute,
|
||||
selecting from <a href="https://boxicons.com">Box Icons</a> or your own custom
|
||||
classes.</li>
|
||||
</ul>
|
||||
<p>For example, if you want to style notes of a specific type, such as notes
|
||||
containing PNG images, you can target them with classes like <code>type-image mime-image-png</code>.</p>
|
||||
containing PNG images, you can target them with classes like <code spellcheck="false">type-image mime-image-png</code>.</p>
|
||||
<h3>User-Provided Themes</h3>
|
||||
<p>A gallery of user-created themes is available, showcasing the variety
|
||||
of customizations that the Trilium community has developed. For more information,
|
||||
check the <a class="reference-link" href="#root/_help_VbjZvtUek0Ln">Theme Gallery</a>.</p>
|
||||
<h3>Asset Path Management</h3>
|
||||
<p>When referencing built-in assets like images in your custom themes or
|
||||
CSS, you can avoid hardcoding version numbers by using the <code>vX</code> alias.
|
||||
For example, instead of specifying <code>/assets/v0.57.0-beta/images/icon-grey.png</code>,
|
||||
you can use <code>/assets/vX/images/icon-grey.png</code> to keep your theme
|
||||
compatible with future versions of Trilium.</p>
|
||||
CSS, you can avoid hardcoding version numbers by using the <code spellcheck="false">vX</code> alias.
|
||||
For example, instead of specifying <code spellcheck="false">/assets/v0.57.0-beta/images/icon-grey.png</code>,
|
||||
you can use <code spellcheck="false">/assets/vX/images/icon-grey.png</code> to
|
||||
keep your theme compatible with future versions of Trilium.</p>
|
||||
76
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Themes/Icon Packs.html
generated
vendored
Normal file
76
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Themes/Icon Packs.html
generated
vendored
Normal file
@ -0,0 +1,76 @@
|
||||
<h2>Importing an existing icon pack</h2>
|
||||
<p>Icon packs are specific to Trilium, so they must either be created from
|
||||
scratch (see below) or imported from a ZIP file from a third-party developer.</p>
|
||||
<aside
|
||||
class="admonition note">
|
||||
<p><strong>Icon packs are third-party content</strong>
|
||||
<br>
|
||||
<br>The Trilium maintainers are not responsible for keeping these icon packs
|
||||
up to date. If you have an issue with a specific icon pack, then the issue
|
||||
must be reported to the third-party developer responsible for it, not the
|
||||
Trilium team.</p>
|
||||
</aside>
|
||||
<p>To import an icon pack:</p>
|
||||
<ol>
|
||||
<li data-list-item-id="e72cd89899a976ca5c54e089df2285d41">Ideally, create a dedicated spot in your note tree where to place the
|
||||
icon packs.</li>
|
||||
<li data-list-item-id="ed7f941fe865c5f14e1ae724831e49ba1">Right click the note where to put it and select <em>Import into note</em>.</li>
|
||||
<li
|
||||
data-list-item-id="e1b6980592dddab6a0235dd070b3b7067">Uncheck <em>Safe import</em>.</li>
|
||||
<li data-list-item-id="edd29376be6fbf3b9c59275145457de3b">Select <em>Import</em>.</li>
|
||||
<li data-list-item-id="ea9ae8004d6cd7b349ac648cde9141977"><a href="#root/pOsGYCXsbNQG/BgmBlOIl72jZ/_help_s8alTXmpFR61">Refresh the application</a>.</li>
|
||||
</ol>
|
||||
<aside class="admonition warning">
|
||||
<p>Since <em>Safe import</em> is disabled, make sure you trust the source as
|
||||
it could contain dangerous third-party scripts. One good way to check if
|
||||
the icon pack is safe is to manually extract the .zip and inspect the file
|
||||
contents. Icon packs should only contain a font file and a JSON file. Other
|
||||
files (especially scripts) are to be considered harmful.</p>
|
||||
</aside>
|
||||
<h2>Creating an icon pack</h2>
|
||||
<p>Creating an icon pack requires some scripting knowledge outside Trilium
|
||||
in order to generate the list of icons. For information, see <a class="reference-link"
|
||||
href="#root/pKK96zzmvBGf/_help_g1mlRoU8CsqC">Creating an icon pack</a>.</p>
|
||||
<h2>Using an icon from an icon pack</h2>
|
||||
<p>After <a href="#root/pOsGYCXsbNQG/BgmBlOIl72jZ/_help_s8alTXmpFR61">refreshing the application</a>,
|
||||
the icon pack should be enabled by default. To test this, simply select
|
||||
an existing note or create a new one and try to change the note icon.</p>
|
||||
<p>There should be a <em>Filter</em> button to the right of the search bar
|
||||
in the icon list. Clicking it allows filtering by icon pack and the newly
|
||||
imported icon pack should be displayed there.</p>
|
||||
<aside class="admonition note">
|
||||
<p>If the icon pack is missing from that list, then most likely there's something
|
||||
wrong with it.</p>
|
||||
<ul>
|
||||
<li data-list-item-id="e0a36a4a12c83b68ed1affd67e7ffa850">Try checking the <a class="reference-link" href="#root/pOsGYCXsbNQG/BgmBlOIl72jZ/qzNzp9LYQyPT/_help_bnyigUA2UK7s">Backend (server) logs</a> for
|
||||
clues and make sure that the icon pack has the <code spellcheck="false">#iconPack</code>
|
||||
<a
|
||||
href="#root/pOsGYCXsbNQG/tC7s2alapj8V/zEY4DaJG4YT5/_help_HI6GBBIduIgv">label</a>with a value assigned to it (a prefix).</li>
|
||||
<li data-list-item-id="e33510913f0656b1c14c5f0c7278093c7">Icon packs that are <a href="#root/pOsGYCXsbNQG/gh7bpGYxajRS/BFs8mudNFgCS/_help_bwg0e8ewQMak">protected</a> are
|
||||
ignored.</li>
|
||||
</ul>
|
||||
</aside>
|
||||
<h2>Integration with the share and export functionality</h2>
|
||||
<p>Custom icon packs are also supported by the <a class="reference-link"
|
||||
href="#root/pOsGYCXsbNQG/tC7s2alapj8V/_help_R9pX4DGra2Vt">Sharing</a> feature,
|
||||
where they will be shown in the note tree. However, in order for an icon
|
||||
pack to be visible to the share function, the icon pack note must also
|
||||
be shared.</p>
|
||||
<p>If you are using a custom share theme, make sure it supports the
|
||||
<code
|
||||
spellcheck="false">iconPackCss</code>, otherwise icons will not show up. Check the original
|
||||
share template source code for reference.</p>
|
||||
<p>Custom icon packs will also be preserved when <a class="reference-link"
|
||||
href="#root/pOsGYCXsbNQG/tC7s2alapj8V/R9pX4DGra2Vt/_help_ycBFjKrrwE9p">Exporting static HTML for web publishing</a>.
|
||||
In this case, there's no requirement to make the icon pack shared.</p>
|
||||
<h2>What happens if I remove an icon pack</h2>
|
||||
<p>If an icon pack is removed or disabled (by removing or altering its
|
||||
<code
|
||||
spellcheck="false">#iconPack</code>label), all the notes that use this icon pack will show
|
||||
in the <a class="reference-link" href="#root/pOsGYCXsbNQG/gh7bpGYxajRS/Vc8PjrjAGuOp/_help_oPVyFC7WL2Lp">Note Tree</a> with
|
||||
no icon. This won't cause any issues apart from looking strange.</p>
|
||||
<p>The solution is to replace the icons with some else, try using
|
||||
<a
|
||||
class="reference-link" href="#root/pOsGYCXsbNQG/gh7bpGYxajRS/wArbEsdSae6g/_help_eIg8jdvaoNNd">Search</a> which supports bulk actions, to identify the notes with
|
||||
the now deleted icon pack (by looking for the prefix) and changing or removing
|
||||
their <code spellcheck="false">iconClass</code>.</p>
|
||||
239
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html
generated
vendored
Normal file
239
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Theme development/Creating an icon pack.html
generated
vendored
Normal file
@ -0,0 +1,239 @@
|
||||
<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 <a class="reference-link"
|
||||
href="#root/Wy267RK4M69c/_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
|
||||
into Trilium.</p>
|
||||
<p>Trilium only supports <strong>font-based icon sets</strong>, with the following
|
||||
formats:</p>
|
||||
<figure class="table">
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Extension</th>
|
||||
<th>MIME type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code spellcheck="false">.woff2</code>
|
||||
</td>
|
||||
<td><code spellcheck="false">font/woff2</code>
|
||||
</td>
|
||||
<td>Recommended due to great compression (low size).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code spellcheck="false">.woff</code>
|
||||
</td>
|
||||
<td><code spellcheck="false">font/woff</code>
|
||||
</td>
|
||||
<td>Higher compatibility, but the font file is bigger.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code spellcheck="false">.ttf</code>
|
||||
</td>
|
||||
<td><code spellcheck="false">font/ttf</code>
|
||||
</td>
|
||||
<td>Most common, but highest font size.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</figure>
|
||||
<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="e8f2e3426d2894ae6cbdafa64dcf0a8d5">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>
|
||||
</ul>
|
||||
<p>In this case, the font must be manually converted to one of the supported
|
||||
formats (ideally <code spellcheck="false">.woff2</code>).</p>
|
||||
<h2>Prerequisites</h2>
|
||||
<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
|
||||
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>
|
||||
</ol>
|
||||
<h2>Step-by-step process</h2>
|
||||
<p>As an example throughout this page, we are going to go through the steps
|
||||
of integrating <a href="https://phosphoricons.com/">Phosphor Icons</a>.</p>
|
||||
<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">{
|
||||
"icons": {
|
||||
"bx-ball": {
|
||||
"glyph": "\ue9c2",
|
||||
"terms": [ "ball" ]
|
||||
},
|
||||
"bxs-party": {
|
||||
"glyph": "\uec92"
|
||||
"terms": [ "party" ]
|
||||
}
|
||||
}
|
||||
}</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>),
|
||||
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.
|
||||
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
|
||||
while hovering over it in the icon selector.</li>
|
||||
</ul>
|
||||
<p>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 <code spellcheck="false">selection.json</code> with
|
||||
the following format:</p><pre><code class="language-application-json">{
|
||||
"icons": [
|
||||
{
|
||||
"icon": {
|
||||
"paths": [ /* [...] */ ],
|
||||
"grid": 0,
|
||||
"attrs": [{}],
|
||||
"isMulticolor": false,
|
||||
"isMulticolor2": false,
|
||||
"tags": ["acorn"]
|
||||
},
|
||||
"attrs": [{}],
|
||||
"properties": {
|
||||
"id": 0,
|
||||
"order": 1513,
|
||||
"name": "acorn",
|
||||
"code": 60314,
|
||||
"ligatures": "acorn",
|
||||
"prevSize": 16
|
||||
},
|
||||
"setIdx": 0,
|
||||
"setId": 0,
|
||||
"iconIdx": 0
|
||||
},
|
||||
/* [...] */
|
||||
]
|
||||
}</code></pre>
|
||||
<p>As such, we can write a Node.js script to automatically process the manifest
|
||||
file:</p><pre><code class="language-application-javascript-env-backend">import { join } from "node:path";
|
||||
import { readFileSync } from "node:fs";
|
||||
|
||||
function processIconPack(packName) {
|
||||
const path = join(packName);
|
||||
const selectionMeta = JSON.parse(readFileSync(join(path, "selection.json"), "utf-8"));
|
||||
const icons = {};
|
||||
|
||||
for (const icon of selectionMeta.icons) {
|
||||
let name = icon.properties.name;
|
||||
if (name.endsWith(`-${packName}`)) {
|
||||
name = name.split("-").slice(0, -1).join("-");
|
||||
}
|
||||
|
||||
const id = `ph-${name}`;
|
||||
icons[id] = {
|
||||
glyph: `${String.fromCharCode(icon.properties.code)}`,
|
||||
terms: [ name ]
|
||||
};
|
||||
}
|
||||
|
||||
return JSON.stringify({
|
||||
icons
|
||||
}, null, 2);
|
||||
}
|
||||
|
||||
console.log(processIconPack("light"));</code></pre>
|
||||
<aside class="admonition tip">
|
||||
<p><strong>Mind the escape format when processing CSS</strong>
|
||||
</p>
|
||||
<p>The Unicode escape syntax is different in CSS (<code spellcheck="false">"\ea3f"</code>)
|
||||
when compared to JSON (<code spellcheck="false">"\uea3f"</code>). Notice
|
||||
how the JSON escape is <code spellcheck="false">\u</code> and not <code spellcheck="false">\</code>.</p>
|
||||
<p>As a more compact alternative, provide the un-escaped character directly,
|
||||
as UTF-8 is supported.</p>
|
||||
</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
|
||||
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>,
|
||||
<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,
|
||||
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>,
|
||||
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
|
||||
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
|
||||
name of the icon pack as displayed in the list of icons.</li>
|
||||
</ol>
|
||||
<h3>Assigning the prefix</h3>
|
||||
<p>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.</p>
|
||||
<p>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: <code spellcheck="false">#iconClass="bx bxs-sushi"</code>.
|
||||
In this case, the icon pack prefix is <code spellcheck="false">bx</code> and
|
||||
the icon class name is <code spellcheck="false">bxs-sushi</code>.</p>
|
||||
<p>In order for an icon pack to be recognized, the prefix must be specified
|
||||
in the <code spellcheck="false">#iconPack</code> label. </p>
|
||||
<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>
|
||||
<h3>Final steps</h3>
|
||||
<ul>
|
||||
<li data-list-item-id="e98981595a95a476c72e23d64017f8bf5"><a href="#root/pOsGYCXsbNQG/BgmBlOIl72jZ/_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
|
||||
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
|
||||
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,
|
||||
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
|
||||
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
|
||||
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,
|
||||
so “Safe mode” must be disabled when importing the ZIP.</li>
|
||||
<li data-list-item-id="eb2c0cfa4acecd022310b293e5b567587">Consider linking new users to the <a class="reference-link" href="#root/pOsGYCXsbNQG/gh7bpGYxajRS/Wy267RK4M69c/_help_gOKqSJgXLcIj">Icon Packs</a> 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 <a class="reference-link"
|
||||
href="#root/pOsGYCXsbNQG/BgmBlOIl72jZ/qzNzp9LYQyPT/_help_bnyigUA2UK7s">Backend (server) logs</a> 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="e0ea23295c4ddec6fa9fe0bf937ffc01b">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>
|
||||
</ul>
|
||||
2
docs/Developer Guide/!!!meta.json
vendored
2
docs/Developer Guide/!!!meta.json
vendored
@ -1,6 +1,6 @@
|
||||
{
|
||||
"formatVersion": 2,
|
||||
"appVersion": "0.100.0",
|
||||
"appVersion": "0.101.1",
|
||||
"files": [
|
||||
{
|
||||
"isClone": false,
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
# Documentation
|
||||
There are multiple types of documentation for Trilium:<img class="image-style-align-right" src="api/images/LZ93RWFQwIO3/Documentation_image.png" width="205" height="162">
|
||||
There are multiple types of documentation for Trilium:<img class="image-style-align-right" src="api/images/elhSPST0fyf2/Documentation_image.png" width="205" height="162">
|
||||
|
||||
* The _User Guide_ represents the user-facing documentation. This documentation can be browsed by users directly from within Trilium, by pressing <kbd>F1</kbd>.
|
||||
* The _Developer's Guide_ represents a set of Markdown documents that present the internals of Trilium, for developers.
|
||||
|
||||
193
docs/User Guide/!!!meta.json
vendored
193
docs/User Guide/!!!meta.json
vendored
@ -1,6 +1,6 @@
|
||||
{
|
||||
"formatVersion": 2,
|
||||
"appVersion": "0.100.0",
|
||||
"appVersion": "0.101.1",
|
||||
"files": [
|
||||
{
|
||||
"isClone": false,
|
||||
@ -4418,38 +4418,52 @@
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "2FvYrpmOXm29",
|
||||
"value": "grjYqerjn243",
|
||||
"isInheritable": false,
|
||||
"position": 100
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "AlhDUqhENtH7",
|
||||
"value": "gBbsAeiuUxI5",
|
||||
"isInheritable": false,
|
||||
"position": 110
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "bwZpz2ajCEwO",
|
||||
"value": "2FvYrpmOXm29",
|
||||
"isInheritable": false,
|
||||
"position": 120
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "KC1HB96bqqHX",
|
||||
"value": "AlhDUqhENtH7",
|
||||
"isInheritable": false,
|
||||
"position": 130
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "0ESUbbAxVnoK",
|
||||
"value": "bwZpz2ajCEwO",
|
||||
"isInheritable": false,
|
||||
"position": 140
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "KC1HB96bqqHX",
|
||||
"isInheritable": false,
|
||||
"position": 150
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "0ESUbbAxVnoK",
|
||||
"isInheritable": false,
|
||||
"position": 160
|
||||
},
|
||||
{
|
||||
"type": "label",
|
||||
"name": "iconClass",
|
||||
@ -4463,20 +4477,6 @@
|
||||
"value": "printing-and-pdf-export",
|
||||
"isInheritable": false,
|
||||
"position": 110
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "grjYqerjn243",
|
||||
"isInheritable": false,
|
||||
"position": 150
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "gBbsAeiuUxI5",
|
||||
"isInheritable": false,
|
||||
"position": 160
|
||||
}
|
||||
],
|
||||
"format": "markdown",
|
||||
@ -5744,6 +5744,97 @@
|
||||
"format": "markdown",
|
||||
"dataFileName": "Theme Gallery.md",
|
||||
"attachments": []
|
||||
},
|
||||
{
|
||||
"isClone": false,
|
||||
"noteId": "gOKqSJgXLcIj",
|
||||
"notePath": [
|
||||
"pOsGYCXsbNQG",
|
||||
"gh7bpGYxajRS",
|
||||
"Wy267RK4M69c",
|
||||
"gOKqSJgXLcIj"
|
||||
],
|
||||
"title": "Icon Packs",
|
||||
"notePosition": 20,
|
||||
"prefix": null,
|
||||
"isExpanded": false,
|
||||
"type": "text",
|
||||
"mime": "text/html",
|
||||
"attributes": [
|
||||
{
|
||||
"type": "label",
|
||||
"name": "iconClass",
|
||||
"value": "bx bx-package",
|
||||
"isInheritable": false,
|
||||
"position": 30
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "g1mlRoU8CsqC",
|
||||
"isInheritable": false,
|
||||
"position": 40
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "s8alTXmpFR61",
|
||||
"isInheritable": false,
|
||||
"position": 50
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "bnyigUA2UK7s",
|
||||
"isInheritable": false,
|
||||
"position": 60
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "HI6GBBIduIgv",
|
||||
"isInheritable": false,
|
||||
"position": 70
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "bwg0e8ewQMak",
|
||||
"isInheritable": false,
|
||||
"position": 80
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "R9pX4DGra2Vt",
|
||||
"isInheritable": false,
|
||||
"position": 90
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "ycBFjKrrwE9p",
|
||||
"isInheritable": false,
|
||||
"position": 100
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "oPVyFC7WL2Lp",
|
||||
"isInheritable": false,
|
||||
"position": 110
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "eIg8jdvaoNNd",
|
||||
"isInheritable": false,
|
||||
"position": 120
|
||||
}
|
||||
],
|
||||
"format": "markdown",
|
||||
"dataFileName": "Icon Packs.md",
|
||||
"attachments": []
|
||||
}
|
||||
]
|
||||
},
|
||||
@ -11801,6 +11892,68 @@
|
||||
"dataFileName": "3_Custom app-wide CSS_image.png"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"isClone": false,
|
||||
"noteId": "g1mlRoU8CsqC",
|
||||
"notePath": [
|
||||
"pOsGYCXsbNQG",
|
||||
"pKK96zzmvBGf",
|
||||
"g1mlRoU8CsqC"
|
||||
],
|
||||
"title": "Creating an icon pack",
|
||||
"notePosition": 50,
|
||||
"prefix": null,
|
||||
"isExpanded": false,
|
||||
"type": "text",
|
||||
"mime": "text/html",
|
||||
"attributes": [
|
||||
{
|
||||
"type": "label",
|
||||
"name": "iconClass",
|
||||
"value": "bx bx-package",
|
||||
"isInheritable": false,
|
||||
"position": 30
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "gOKqSJgXLcIj",
|
||||
"isInheritable": false,
|
||||
"position": 40
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "0vhv7lsOLy82",
|
||||
"isInheritable": false,
|
||||
"position": 50
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "s8alTXmpFR61",
|
||||
"isInheritable": false,
|
||||
"position": 60
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "bnyigUA2UK7s",
|
||||
"isInheritable": false,
|
||||
"position": 70
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "mHbBMPDPkVV5",
|
||||
"isInheritable": false,
|
||||
"position": 80
|
||||
}
|
||||
],
|
||||
"format": "markdown",
|
||||
"dataFileName": "Creating an icon pack.md",
|
||||
"attachments": []
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
50
docs/User Guide/User Guide/Basic Concepts and Features/Themes/Icon Packs.md
vendored
Normal file
50
docs/User Guide/User Guide/Basic Concepts and Features/Themes/Icon Packs.md
vendored
Normal file
@ -0,0 +1,50 @@
|
||||
# Icon Packs
|
||||
## Importing an existing icon pack
|
||||
|
||||
Icon packs are specific to Trilium, so they must either be created from scratch (see below) or imported from a ZIP file from a third-party developer.
|
||||
|
||||
> [!NOTE]
|
||||
> **Icon packs are third-party content**
|
||||
>
|
||||
> The Trilium maintainers are not responsible for keeping these icon packs up to date. If you have an issue with a specific icon pack, then the issue must be reported to the third-party developer responsible for it, not the Trilium team.
|
||||
|
||||
To import an icon pack:
|
||||
|
||||
1. Ideally, create a dedicated spot in your note tree where to place the icon packs.
|
||||
2. Right click the note where to put it and select _Import into note_.
|
||||
3. Uncheck _Safe import_.
|
||||
4. Select _Import_.
|
||||
5. [Refresh the application](../../Troubleshooting/Refreshing%20the%20application.md).
|
||||
|
||||
> [!WARNING]
|
||||
> Since _Safe import_ is disabled, make sure you trust the source as it could contain dangerous third-party scripts. One good way to check if the icon pack is safe is to manually extract the .zip and inspect the file contents. Icon packs should only contain a font file and a JSON file. Other files (especially scripts) are to be considered harmful.
|
||||
|
||||
## Creating an icon pack
|
||||
|
||||
Creating an icon pack requires some scripting knowledge outside Trilium in order to generate the list of icons. For information, see <a class="reference-link" href="../../Theme%20development/Creating%20an%20icon%20pack.md">Creating an icon pack</a>.
|
||||
|
||||
## Using an icon from an icon pack
|
||||
|
||||
After [refreshing the application](../../Troubleshooting/Refreshing%20the%20application.md), the icon pack should be enabled by default. To test this, simply select an existing note or create a new one and try to change the note icon.
|
||||
|
||||
There should be a _Filter_ button to the right of the search bar in the icon list. Clicking it allows filtering by icon pack and the newly imported icon pack should be displayed there.
|
||||
|
||||
> [!NOTE]
|
||||
> If the icon pack is missing from that list, then most likely there's something wrong with it.
|
||||
>
|
||||
> * Try checking the <a class="reference-link" href="../../Troubleshooting/Error%20logs/Backend%20(server)%20logs.md">Backend (server) logs</a> for clues and make sure that the icon pack has the `#iconPack` [label](../../Advanced%20Usage/Attributes/Labels.md) with a value assigned to it (a prefix).
|
||||
> * Icon packs that are [protected](../Notes/Protected%20Notes.md) are ignored.
|
||||
|
||||
## Integration with the share and export functionality
|
||||
|
||||
Custom icon packs are also supported by the <a class="reference-link" href="../../Advanced%20Usage/Sharing.md">Sharing</a> feature, where they will be shown in the note tree. However, in order for an icon pack to be visible to the share function, the icon pack note must also be shared.
|
||||
|
||||
If you are using a custom share theme, make sure it supports the `iconPackCss`, otherwise icons will not show up. Check the original share template source code for reference.
|
||||
|
||||
Custom icon packs will also be preserved when <a class="reference-link" href="../../Advanced%20Usage/Sharing/Exporting%20static%20HTML%20for%20web%20.md">Exporting static HTML for web publishing</a>. In this case, there's no requirement to make the icon pack shared.
|
||||
|
||||
## What happens if I remove an icon pack
|
||||
|
||||
If an icon pack is removed or disabled (by removing or altering its `#iconPack` label), all the notes that use this icon pack will show in the <a class="reference-link" href="../UI%20Elements/Note%20Tree.md">Note Tree</a> with no icon. This won't cause any issues apart from looking strange.
|
||||
|
||||
The solution is to replace the icons with some else, try using <a class="reference-link" href="../Navigation/Search.md">Search</a> which supports bulk actions, to identify the notes with the now deleted icon pack (by looking for the prefix) and changing or removing their `iconClass`.
|
||||
174
docs/User Guide/User Guide/Theme development/Creating an icon pack.md
vendored
Normal file
174
docs/User Guide/User Guide/Theme development/Creating an icon pack.md
vendored
Normal file
@ -0,0 +1,174 @@
|
||||
# Creating an icon pack
|
||||
> [!NOTE]
|
||||
> e This page describes how to create custom icon packs. For a general description of how to use already existing icon packs, see <a class="reference-link" href="../Basic%20Concepts%20and%20Features/Themes/Icon%20Packs.md">Icon Packs</a>.
|
||||
|
||||
## Supported formats
|
||||
|
||||
The first step is to analyze if the icon set being packed can be integrated into Trilium.
|
||||
|
||||
Trilium only supports **font-based icon sets**, with the following formats:
|
||||
|
||||
| Extension | MIME type | Description |
|
||||
| --- | --- | --- |
|
||||
| `.woff2` | `font/woff2` | Recommended due to great compression (low size). |
|
||||
| `.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.
|
||||
* Individual SVGs.
|
||||
* `.eot` fonts (legacy and proprietary).
|
||||
* Duotone icons, since it requires a special CSS format that Trilium doesn't support.
|
||||
* Any other font format not specified in the _Supported formats_ section.
|
||||
|
||||
In this case, the font must be manually converted to one of the supported formats (ideally `.woff2`).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
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. 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.
|
||||
|
||||
## Step-by-step process
|
||||
|
||||
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" ]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* 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.
|
||||
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"icons": [
|
||||
{
|
||||
"icon": {
|
||||
"paths": [ /* [...] */ ],
|
||||
"grid": 0,
|
||||
"attrs": [{}],
|
||||
"isMulticolor": false,
|
||||
"isMulticolor2": false,
|
||||
"tags": ["acorn"]
|
||||
},
|
||||
"attrs": [{}],
|
||||
"properties": {
|
||||
"id": 0,
|
||||
"order": 1513,
|
||||
"name": "acorn",
|
||||
"code": 60314,
|
||||
"ligatures": "acorn",
|
||||
"prevSize": 16
|
||||
},
|
||||
"setIdx": 0,
|
||||
"setId": 0,
|
||||
"iconIdx": 0
|
||||
},
|
||||
/* [...] */
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
As such, we can write a Node.js script to automatically process the manifest file:
|
||||
|
||||
```javascript
|
||||
import { join } from "node:path";
|
||||
import { readFileSync } from "node:fs";
|
||||
|
||||
function processIconPack(packName) {
|
||||
const path = join(packName);
|
||||
const selectionMeta = JSON.parse(readFileSync(join(path, "selection.json"), "utf-8"));
|
||||
const icons = {};
|
||||
|
||||
for (const icon of selectionMeta.icons) {
|
||||
let name = icon.properties.name;
|
||||
if (name.endsWith(`-${packName}`)) {
|
||||
name = name.split("-").slice(0, -1).join("-");
|
||||
}
|
||||
|
||||
const id = `ph-${name}`;
|
||||
icons[id] = {
|
||||
glyph: `${String.fromCharCode(icon.properties.code)}`,
|
||||
terms: [ name ]
|
||||
};
|
||||
}
|
||||
|
||||
return JSON.stringify({
|
||||
icons
|
||||
}, null, 2);
|
||||
}
|
||||
|
||||
console.log(processIconPack("light"));
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> **Mind the escape format when processing CSS**
|
||||
>
|
||||
> The Unicode escape syntax is different in CSS (`"\ea3f"`) when compared to JSON (`"\uea3f"`). Notice how the JSON escape is `\u` and not `\`.
|
||||
>
|
||||
> 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.
|
||||
|
||||
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
|
||||
|
||||
* [Refresh the client](../Troubleshooting/Refreshing%20the%20application.md)
|
||||
* Change the icon of the note and look for the _Filter_ icon in the top-right side.
|
||||
* Check if the new icon pack is displayed there and click on it to see the full list of icons.
|
||||
* 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).
|
||||
* 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 <a class="reference-link" href="../Basic%20Concepts%20and%20Features/Themes/Icon%20Packs.md">Icon Packs</a> 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 <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.
|
||||
Loading…
x
Reference in New Issue
Block a user