From 9b2876a8ff82f8b25a7c0e4753e7f1d7781764d6 Mon Sep 17 00:00:00 2001 From: Elian Doran Date: Sun, 15 Feb 2026 17:47:28 +0200 Subject: [PATCH] docs(user): mention custom tiles & hiding labels for geomap --- .../Active content.html | 200 +++--- .../User Guide/Collections/Geo Map.html | 633 +++++++++--------- .../User Guide/Note Types/Render Note.html | 32 +- .../User Guide/Scripting/Backend scripts.html | 20 +- .../Scripting/Backend scripts/Events.html | 256 ++++--- .../User Guide/Scripting/Frontend Basics.html | 85 ++- .../Frontend Basics/Custom Widgets.html | 153 +++-- .../Frontend Basics/Launch Bar Widgets.html | 17 +- .../Developer Guide/Documentation.md | 2 +- docs/User Guide/!!!meta.json | 502 +++++++------- docs/User Guide/User Guide.md | 2 +- .../User Guide/Collections/Geo Map.md | 31 +- 12 files changed, 974 insertions(+), 959 deletions(-) diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Active content.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Active content.html index f45db3c93d..cc2294d9ef 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Active content.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Active content.html @@ -5,116 +5,109 @@

Active content problem of safety, especially when this active content comes from a third-party such as if it is downloaded from a website and then imported into Trilium.

-

When importing .zip - archives into Trilium, safe mode is active by default which will - try to prevent untrusted code from executing. For example, a custom widget needs - the #widget label in - order to function; safe import works by renaming that label to #disabled:widget.

+

When importing .zip archives into Trilium, safe mode is + active by default which will try to prevent untrusted code from executing. + For example, a custom widget needs the + #widget label in order to function; + safe import works by renaming that label to #disabled:widget.

Safe mode

Sometimes active content can cause issues with the UI or the server, preventing - it from functioning properly. Safe mode allows + it from functioning properly. Safe mode allows starting Trilium in such a way that active content is not loaded by default at start-up, allowing the user to fix the problematic scripts or widgets.

Types of active content

These are the types of active content in Trilium, along with a few examples of what untrusted content of that type could cause:

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameDisabled on a safe import - DescriptionPotential risks of untrusted code
Front-end scripts - YesAllow running arbitrary code on the client (UI) of Trilium, which can - alter the user interface.A malicious script can execute server-side code, access un-encrypted notes - or change their contents.
Custom Widgets - YesCan add new UI features to Trilium, for example by adding a new section - in the Right Sidebar.The UI can be altered in such a way that it can be used to extract sensitive - information or it can simply cause the application to crash.
Backend scripts - YesCan run custom code on the server of Trilium (Node.js environment), with - full access to the notes and the database.Has access to all the unencrypted notes, but with full access to the database - it can completely destroy the data. It also has access to execute other - applications or alter the files and folders on the server).
Web View - YesDisplays a website inside a note.Can point to a phishing website which can collect the data (for example - on a log in page).
Render Note - YesRenders custom content inside a note, such as a dashboard or a new editor - that is not officially supported by Trilium.Can affect the UI similar to front-end scripts or custom widgets since - the scripts are not completely encapsulated, or they can act similar to - a web view where they can collect data entered by the user.
Custom app-wide CSS - NoCan alter the layout and style of the UI using CSS, applied regardless - of theme.Generally less problematic than the rest of active content, but a badly - written CSS can affect the layout of the application, requiring the use - of Safe mode to - be able to use the application.
Custom themes - NoCan change the style of the entire UI.Similar to custom app-wide CSS.
Icon Packs - NoIntroduces new icons that can be used for notes.Generally are more contained and less prone to cause issues, but they - can cause performance issues (for example if the icon pack has millions - of icons in it).
-
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDisabled on a safe import + DescriptionPotential risks of untrusted code
Front-end scripts + YesAllow running arbitrary code on the client (UI) of Trilium, which can + alter the user interface.A malicious script can execute server-side code, access un-encrypted notes + or change their contents.
Custom Widgets + YesCan add new UI features to Trilium, for example by adding a new section + in the Right Sidebar.The UI can be altered in such a way that it can be used to extract sensitive + information or it can simply cause the application to crash.
Backend scripts + YesCan run custom code on the server of Trilium (Node.js environment), with + full access to the notes and the database.Has access to all the unencrypted notes, but with full access to the database + it can completely destroy the data. It also has access to execute other + applications or alter the files and folders on the server).
Web View + YesDisplays a website inside a note.Can point to a phishing website which can collect the data (for example + on a log in page).
Render Note + YesRenders custom content inside a note, such as a dashboard or a new editor + that is not officially supported by Trilium.Can affect the UI similar to front-end scripts or custom widgets since + the scripts are not completely encapsulated, or they can act similar to + a web view where they can collect data entered by the user.
Custom app-wide CSS + NoCan alter the layout and style of the UI using CSS, applied regardless + of theme.Generally less problematic than the rest of active content, but a badly + written CSS can affect the layout of the application, requiring the use + of Safe mode to + be able to use the application.
Custom themes + NoCan change the style of the entire UI.Similar to custom app-wide CSS.
Icon Packs + NoIntroduces new icons that can be used for notes.Generally are more contained and less prone to cause issues, but they + can cause performance issues (for example if the icon pack has millions + of icons in it).
+

Active content badge

-

Starting with v0.102.0, on the New Layout a +

Starting with v0.102.0, on the New Layout a badge will be displayed near the note title, indicating that an active content is detected. Clicking the badge will reveal a menu with various options related to that content type, for example to open the documentation @@ -122,5 +115,4 @@ style="width:100%;">

For some active content types, such as backend scripts with custom triggering conditions a toggle button will appear. This makes it possible to easily disable scripts or widgets, but also to re-enable them if an import was - made with safe mode active.

-

 

\ No newline at end of file + made with safe mode active.

\ No newline at end of file diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Collections/Geo Map.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Collections/Geo Map.html index cfee0ce25f..e86e58f98a 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Collections/Geo Map.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Collections/Geo Map.html @@ -1,9 +1,8 @@

Creating a new geo map

- - - - - - - - - - - - - - - - - - - - -
1 -
- -
- 		Right click on any note on the note tree and select Insert child note → Geo Map (beta).
2 -
- -
- 		By default the map will be empty and will show the entire world.
- +
+ + + + + + + + + + + + + + + + + + + + +
   
1 +
+ +
+ 		Right click on any note on the note tree and select Insert child note → Geo Map (beta).
2 +
+ +
+ 		By default the map will be empty and will show the entire world.
+

Repositioning the map

@@ -206,211 +213,239 @@ width="1288" height="278">

The value of the attribute is made up of the latitude and longitude separated by a comma.

Adding from Google Maps

- - - - - - - - - - - - - - - - - - - - - - - - - -
1 -
- -
- 		Go to Google Maps on the web and look for a desired location, right click - on it and a context menu will show up.        -
-
Simply click on the first item displaying the coordinates and they will - be copied to clipboard.        -
-
Then paste the value inside the text box into the #geolocation attribute - of a child note of the map (don't forget to surround the value with a - "character).
2 -
- -
- 		In Trilium, create a child note under the map.
3 -
- -
- 		And then go to Owned Attributes and type #geolocation=", - then paste from the clipboard as-is and then add the ending " character. - Press Enter to confirm and the map should now be updated to contain the - new note.
- +
+ + + + + + + + + + + + + + + + + + + + + + + + + +
   
1 +
+ +
+ 		Go to Google Maps on the web and look for a desired location, right click + on it and a context menu will show up.         +
+
Simply click on the first item displaying the coordinates and they will + be copied to clipboard.         +
+
Then paste the value inside the text box into the #geolocation attribute + of a child note of the map (don't forget to surround the value with a + "character).
2 +
+ +
+ 		In Trilium, create a child note under the map.
3 +
+ +
+ 		And then go to Owned Attributes and type #geolocation=", + then paste from the clipboard as-is and then add the ending " character. + Press Enter to confirm and the map should now be updated to contain the + new note.
+

Adding from OpenStreetMap

Similarly to the Google Maps approach:

- - - - - - - - - - - - - - - - - - - - - - - - - -
1 - - Go to any location on openstreetmap.org and right click to bring up the - context menu. Select the “Show address” item.
2 - - The address will be visible in the top-left of the screen, in the place - of the search bar.        -
-
Select the coordinates and copy them into the clipboard.
3 - - Simply paste the value inside the text box into the #geolocation attribute - of a child note of the map and then it should be displayed on the map.
- +
+ + + + + + + + + + + + + + + + + + + + + + + + + +
   
1 + + Go to any location on openstreetmap.org and right click to bring up the + context menu. Select the “Show address” item.
2 + + The address will be visible in the top-left of the screen, in the place + of the search bar.         +
+
Select the coordinates and copy them into the clipboard.
3 + + Simply paste the value inside the text box into the #geolocation attribute + of a child note of the map and then it should be displayed on the map.
+

Adding GPS tracks (.gpx)

Trilium has basic support for displaying GPS tracks on the geo map.

- - - - - - - - - - - - - - - - - - - - - - - - - -
1 -
- -
- 		To add a track, simply drag & drop a .gpx file inside the geo map - in the note tree.
2 -
- -
- 		In order for the file to be recognized as a GPS track, it needs to show - up as application/gpx+xml in the File type field.
3 -
- -
- 		When going back to the map, the track should now be visible.        -
-
The start and end points of the track are indicated by the two blue markers.
- -

Read-only mode

-

When a map is in read-only all editing features will be disabled such - as:

- -

To enable read-only mode simply press the Lock icon from the  - Floating buttons. To disable it, press the button again.

-

Configuration

-

Map Style

-

The styling of the map can be adjusted in the Collection Properties tab - in the Ribbon or - manually via the #map:style attribute.

-

The geo map comes with two different types of styles:

-
-

Render Note is a special case of front-end scripting which +

Render Note is a special case of front-end scripting which allows rendering custom content inside a note. This makes it possible to create custom dashboards, or to use a custom note editor.

The content can either be a vanilla HTML, or Preact JSX.

@@ -13,13 +13,11 @@
  1. HTML language for the legacy/vanilla method, with what needs to be displayed (for example <p>Hello world.</p>).
    2. -
  2. JSX for the Preact-based approach (see below).
    3. -
+
  • JSX for the Preact-based approach (see below).
    • +
  • Create a Render Note.
    • -
  • Assign the renderNote relation to +
  • Assign the renderNote relation to point at the previously created code note.

    • Legacy scripting using jQuery

    @@ -48,9 +46,10 @@ $dateEl.text(new Date()); need to provide a HTML anymore.

    Here are the steps to creating a simple render note:

      -
    1. Create a note of type Render Note.
      2. -
    2. +
    3. +

      Create a note of type Render Note.

      +
      4. +

    4. Create a child Code note with JSX as the language.
      As an example, use the following content:

      export default function() {
@@ -60,17 +59,20 @@ $dateEl.text(new Date());
      </> ); } -
      5. -
    5. In the parent render note, define a ~renderNote relation - pointing to the newly created child.
      6. -
    6. Refresh the render note and it should display a “Hello world” message.
      7. + +
    7. +

      In the parent render note, define a ~renderNote relation + pointing to the newly created child.

      +
      8. +
    8. +

      Refresh the render note and it should display a “Hello world” message.

      +

    Refreshing the note

    It's possible to refresh the note via:

    Examples

    diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Backend scripts.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Backend scripts.html index 80cbebbfeb..8691c4c054 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Backend scripts.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Backend scripts.html @@ -1,11 +1,11 @@ -

    Unlike front-end scripts which - run on the client / browser-side, back-end scripts run directly on the - Node.js environment of the Trilium server.

    +

    Unlike front-end scripts which run on the + client / browser-side, back-end scripts run directly on the Node.js environment + of the Trilium server.

    Back-end scripts can be used both on a Server Installation (where - it will run on the device the server is running on), or on the  - Desktop Installation (where it will run on the PC).

    + href="#root/_help_WOcw2SLH6tbX">Server Installation (where it will run + on the device the server is running on), or on the Desktop Installation (where it will + run on the PC).

    Advantages of backend scripts

    The benefit of backend scripts is that they can be pretty powerful, for example to have access to the underlying system, for example it can read @@ -14,7 +14,7 @@ access to the notes since the information about them is already loaded in memory. Whereas on the client, notes have to be manually loaded first.

    Creating a backend script

    -

    Create a new Code note +

    Create a new Code note and select the language JS backend.

    Running backend scripts

    Backend scripts can be either run manually (via the Execute button on @@ -22,8 +22,8 @@

    In addition, scripts can be run automatically when the server starts up, on a fixed time interval or when a certain event occurs (such as an attribute being modified). For more information, see the dedicated Events page.

    + href="#root/_help_GPERMystNGTB">Events page.

    Script API

    Trilium exposes a set of APIs that can be directly consumed by scripts, under the api object. For a reference of - this API, see Backend API.

    \ No newline at end of file + this API, see Backend API.

    \ No newline at end of file diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Backend scripts/Events.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Backend scripts/Events.html index 3e54232a5d..de4beda67f 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Backend scripts/Events.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Backend scripts/Events.html @@ -5,139 +5,137 @@

    Global events are attached to the script note via label. Simply create e.g. "run" label with some of these values and script note will be executed once the event occurs.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    LabelDescription
    run - -

    Defines on which events script should run. Possible values are:

    -
      -
    • backendStartup - when Trilium backend starts - up
      • -
    • hourly - run once an hour. You can use - additional label runAtHour to specify at - which hour, on the back-end.
      • -
    • daily - run once a day, on the back-end
      • -
    -
    runOnInstance - Specifies that the script should only run on a particular Trilium instance.
    runAtHour - On which hour should this run. Should be used together with #run=hourly. - Can be defined multiple times for more runs during the day.
    -
    + + + + + + + + + + + + + + + + + + + + + +
    LabelDescription
    run + +

    Defines on which events script should run. Possible values are:

    +
      +
    • backendStartup - when Trilium backend starts + up
      • +
    • hourly - run once an hour. You can use + additional label runAtHour to specify at + which hour, on the back-end.
      • +
    • daily - run once a day, on the back-end
      • +
    +
    runOnInstance + Specifies that the script should only run on a particular Trilium instance.
    runAtHour + On which hour should this run. Should be used together with #run=hourly. + Can be defined multiple times for more runs during the day.
    +

    Entity events

    Other events are bound to some entity, these are defined as relations - meaning that script is triggered only if note has this script attached to it through relations (or it can inherit it).

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    RelationTrigger conditionOrigin entity (see below)
    runOnNoteCreation - executes when note is created on backend. Use this relation if you want - to run the script for all notes created under a specific subtree. In that - case, create it on the subtree root note and make it inheritable. A new - note created within the subtree (any depth) will trigger the script.The BNote that got created.
    runOnChildNoteCreation - executes when new note is created under the note where this relation is - definedThe BNote of the child that got created.
    runOnNoteTitleChange - executes when note title is changed (includes note creation as well)The BNote of the note whose title got changed.
    runOnNoteContentChange - executes when note content is changed (includes note creation as well).The BNote of the note whose content got - changed.
    runOnNoteChange - executes when note is changed (includes note creation as well). Does not - include content changesThe BNote of the note that got changed.
    runOnNoteDeletion - executes when note is being deletedThe BNote of the note that got (soft) deleted.
    runOnBranchCreation - executes when a branch is created. Branch is a link between parent note - and child note and is created e.g. when cloning or moving note.The BBranch that got created.
    runOnBranchChange - executes when a branch is updated. (since v0.62)The BBranch that got changed.
    runOnBranchDeletion - executes when a branch is deleted. Branch is a link between parent note - and child note and is deleted e.g. when moving note (old branch/link is - deleted).The BBranch that got (soft) deleted.
    runOnAttributeCreation - executes when new attribute is created for the note which defines this - relationThe BAttribute that got created.
    runOnAttributeChange - executes when the attribute is changed of a note which defines this relation. - This is triggered also when the attribute is deletedThe BAttribute that got changed.
    -
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RelationTrigger conditionOrigin entity (see below)
    runOnNoteCreation + executes when note is created on backend. Use this relation if you want + to run the script for all notes created under a specific subtree. In that + case, create it on the subtree root note and make it inheritable. A new + note created within the subtree (any depth) will trigger the script.The BNote that got created.
    runOnChildNoteCreation + executes when new note is created under the note where this relation is + definedThe BNote of the child that got created.
    runOnNoteTitleChange + executes when note title is changed (includes note creation as well)The BNote of the note whose title got changed.
    runOnNoteContentChange + executes when note content is changed (includes note creation as well).The BNote of the note whose content got + changed.
    runOnNoteChange + executes when note is changed (includes note creation as well). Does not + include content changesThe BNote of the note that got changed.
    runOnNoteDeletion + executes when note is being deletedThe BNote of the note that got (soft) deleted.
    runOnBranchCreation + executes when a branch is created. Branch is a link between parent note + and child note and is created e.g. when cloning or moving note.The BBranch that got created.
    runOnBranchChange + executes when a branch is updated. (since v0.62)The BBranch that got changed.
    runOnBranchDeletion + executes when a branch is deleted. Branch is a link between parent note + and child note and is deleted e.g. when moving note (old branch/link is + deleted).The BBranch that got (soft) deleted.
    runOnAttributeCreation + executes when new attribute is created for the note which defines this + relationThe BAttribute that got created.
    runOnAttributeChange + executes when the attribute is changed of a note which defines this relation. + This is triggered also when the attribute is deletedThe BAttribute that got changed.
    +

    Origin entity

    When a script is run by an event such as the ones described above, Front-end scripts are custom JavaScript notes that are run on the client (browser environment)

    There are four flavors of front-end scripts:

    -
    - - - - - - - - - - - - - - - - - - - - - - - -
    Regular scriptsThese are run with the current app and note context. These can be run - either manually or automatically on start-up.
    Custom Widgets - These can introduce new UI elements in various positions, such as near - the Note Tree, - content area or even the Right Sidebar.
    Launch Bar Widgets - Similar to Custom Widgets, - but dedicated to the Launch Bar. - These can simply introduce new buttons or graphical elements to the bar.
    Render Note - This allows rendering custom content inside a note, using either HTML - or Preact JSX.
    -
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    Regular scriptsThese are run with the current app and note context. These can be run + either manually or automatically on start-up.
    Custom Widgets + These can introduce new UI elements in various positions, such as near + the Note Tree, + content area or even the Right Sidebar.
    Launch Bar Widgets + Similar to Custom Widgets, + but dedicated to the Launch Bar. + These can simply introduce new buttons or graphical elements to the bar.
    Render Note + This allows rendering custom content inside a note, using either HTML + or Preact JSX.

    For more advanced behaviors that do not require a user interface (e.g. - batch modifying notes), see Backend scripts.

    + batch modifying notes), see Backend scripts.

    Scripts

    Scripts don't have any special requirements. They can be run manually using the Execute button on the code note or they can be run automatically; - to do so, set the run label to + to do so, set the run label to either: