diff --git a/README.md b/README.md index 0690cc2..818f111 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,77 @@ -# Trilium Next documentation +# TriliumNext Documentation -This is an export of the upsteam [Zadam Wiki][0] for Trilium Notes. It's been converted from Github wiki format to markdown with some light rearranging to make for better presentation when imported into Trilium. It's anticipdated that in time this will supercede Zadam Wiki. +To import this documentation into your own instance of Trilium, [follow these instructions](Wiki/import-docs.md) -## Importing +## Table of Contents -To import these docs into your own Trilium instance: - -1. Download archive from main branch of this repo: -https://github.com/TriliumNext/Docs/archive/refs/heads/main.zip -2. In Trilim create a new note to act as branch for the docs -3. Right-click >> Import into note >> select downloaded `Docs-main.zip` - a. optionally uncheck "Shrink images" - -### Optional cleanup -- delete `!!!meta.json` -- Move `images` node down to the bottom (instead of dragging, it's easier to move out to parent node than back into Wiki. It will go to end of list automatically). - -For new releases delete the old docs note tree and start fresh, or you'll get duplicates. - -[0]: https://github.com/zadam/trilium/wiki +- [Quick Start](Wiki/quick-start.md) +- [Screenshot Tour](Wiki/screenshot-tour.md) +- Basic Concepts + - [Documents](Wiki/document.md) + - [Note](Wiki/note.md) + - [Text Notes](Wiki/text-notes.md) + - [Links](Wiki/links.md) + - [Images](Wiki/images.md) + - [Attachments](Wiki/attachments.md) + - [Cloning notes](Wiki/cloning-notes.md) + - [Protected Notes](Wiki/protected-notes.md) + - [Archived Notes](Wiki/archived-notes.md) + - [Note Revisions](Wiki/note-revisions.md) + - Navigation + - [Tree Concepts](Wiki/tree-concepts.md) + - [Tree Manipulation](Wiki/tree-manipulation.md) + - [Note Navigation](Wiki/note-navigation.md) + - [Search](Wiki/search.md) + - [Bookmarks](Wiki/bookmarks.md) + - [Note Hoisting](Wiki/note-hoisting.md) + - [Workspace](Wiki/workspace.md) + - [Keyboard Shortcuts](Wiki/keyboard-shortcuts.md) + - [Themes](Wiki/themes.md) + - [Theme Gallery](Wiki) + - Import & Export + - [Markdown](Wiki/markdown.md) + - [Evernote](Wiki/evernote-import.md) + - [OneNote](Wiki/onenote.md) +- Installation & Setup + - [Desktop Installation](Wiki/desktop-installation.md) + - [Server Installation](Wiki/server-installation.md) + - [Packaged Server Installation](Wiki/packaged-server-installation.md) + - [Docker Server Installation](Wiki/docker-server-installation.md) + - [NixOS Server Installation](Wiki/nixos-server-installation.md) + - [Manual Server Installation](Wiki/manual-server-installation.md) + - [Kubernettes Server Installation](Wiki/kubernetes-server-installation.md) + - [Apache Proxy Setup](Wiki/apache-proxy-setup.md) + - [Nginx Proxy Setup](Wiki/nginx-proxy-setup.md) + - [TLS Configuration](Wiki/tls-configuration.md) + - [Synchronization](Wiki/synchronization.md) + - [Mobile Frontend](Wiki/mobile-frontend.md) + - [Web Clipper](Wiki/web-clipper.md) + - [Upgrading Trilium](Wiki/upgrading-trilium.md) + - [Backup](Wiki/backup.md) + - [Data Directory](Wiki/data-directory.md) +- Advanced Usage + - [Attributes](Wiki/attributes.md) + - [Attribute Inheritance](Wiki/attribute-inheritance.md) + - [Promoted Attributes](Wiki/promoted-attributes.md) + - [Template](Wiki/template.md) + - [Relation Map](Wiki/relation-map.md) + - [Note Map](Wiki/note-map.md) + - [Book Note](Wiki/book-note.md) + - [Sharing](Wiki/sharing.md) + - [Code Notes](Wiki/code-notes.md) + - [Scripts](Wiki/scripts.md) + - [Script API](Wiki/script-api.md) + - [Custom Request handler](Wiki/custom-request-handler.md) + - [Events](Wiki/events.md) + - [Custom Widgets](Wiki/custom-widget.md) + - [Advanced Showcase](Wiki/advanced-showcases.md) + - [Day Notes](Wiki/day-notes.md) + - [Weight Tracker](Wiki/weight-tracker.md) + - [Task Manager](Wiki/task-manager.md) + - [ETAPI (Rest API)](Wiki/etapi.md) + - [Default Note Title](Wiki/default-note-title.md) +- Developer Guides + - [Frontend Basics](Wiki/frontend-basics.md) + - [Widget Basics](Wiki/widget-basics.md) +- [FAQ](Wiki/faq.md) +- [Troubleshooting](Wiki/troubleshooting.md) diff --git a/Wiki/advanced-showcases.md b/Wiki/advanced-showcases.md new file mode 100644 index 0000000..253a236 --- /dev/null +++ b/Wiki/advanced-showcases.md @@ -0,0 +1,9 @@ +# Advanced showcases +Trilium provides some advanced functionality in the form of [Scripts](scripts.md) and [promoted attributes](promoted-attributes.md). To explain and visualize these features we've prepared few showcases which are also available in the [demo document](document.md): + +* [Relation map](relation-map.md) +* [Day notes](day-notes.md) +* [Weight Tracker](weight-tracker.md) +* [Task Manager](task-manager.md) + +An important thing to keep in mind is that above showcases and demoed functionality are not built-in into Trilium - these are just examples of Trilium's extensibility. diff --git a/Wiki/anonymized-database.md b/Wiki/anonymized-database.md new file mode 100644 index 0000000..54f79d5 --- /dev/null +++ b/Wiki/anonymized-database.md @@ -0,0 +1,20 @@ +# Anonymized database +### Anonymized database + +In some cases, it's necessary to see the database structure to be able to debug the problem. Of course, we can't ask you to send us [Document](document.md) file with your notes. + +For this, Trilium supports anonymization of the database - you can trigger this in Options -> Advanced tab. + +![](images/anonymization.png) + +This will create a copy of your document and remove all sensitive data (currently note titles, contents, revisions, history and some of the options, and non-system attributes) while leaving all structure and metadata (e.g. date of last change). After this is done, the database is [VACUUMed](https://sqlite.org/lang_vacuum.html) to make sure there's no stale sensitive data in the document file. The resulting file is stored in `anonymized` directory (placed in the [data directory](data-directory.md)). You can safely attach it with your bug report or send it to [zadam.apps@gmail.com](#root/N3Zt66yETj9g) %%{WARNING}%% + +#### Command line anonymization + +If the database is corrupted in a way which prevents Trilium to start up, you won't be able to trigger the anonymization from the UI. For such a case, anonymization is also available from command line: + +```text-plain +node src/anonymize.js +``` + +This needs to be executed in the directory with Trilium source files, for desktop builds this in `resources/app` directory. diff --git a/Wiki/apache-proxy-setup.md b/Wiki/apache-proxy-setup.md new file mode 100644 index 0000000..cffff2d --- /dev/null +++ b/Wiki/apache-proxy-setup.md @@ -0,0 +1,88 @@ +# Apache proxy setup +I've assumed you have created a DNS A record for `trilium.yourdomain.com` that you want to use for your Trilium server. + +1. Download docker image and create container + + ```text-plain + docker pull zadam/trilium:[VERSION] %%{WARNING}%% + docker create --name trilium -t -p 127.0.0.1:8080:8080 -v ~/trilium-data:/home/node/trilium-data zadam/trilium:[VERSION] + ``` + +2. Configure Apache proxy and websocket proxy + + 1. Enable apache proxy modules + + ```text-plain + a2enmod ssl + a2enmod proxy + a2enmod proxy_http + a2enmod proxy_wstunnel + ``` + + 2. Create a new let's encrypt certificate + + ```text-plain + sudo certbot certonly -d trilium.mydomain.com + ``` + + Choose standalone (2) and note the location of the created certificates (typically /etc/letsencrypt/live/...) + + 3. Create a new virtual host file for apache (you may want to use `apachectl -S` to determine the server root location, mine is /etc/apache2) + + ```text-plain + sudo nano /etc/apache2/sites-available/trilium.yourdomain.com.conf + ``` + + Paste (and customize) the following text into the configuration file + + ```text-plain + + ServerName http://trilium.yourdomain.com + RewriteEngine on + RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,QSA,R=permanent] + + + ServerName https://trilium.yourdomain.com + RewriteEngine On + RewriteCond %{HTTP:Connection} Upgrade [NC] + RewriteCond %{HTTP:Upgrade} websocket [NC] + RewriteRule /(.*) ws://localhost:8080/$1 [P,L] + AllowEncodedSlashes NoDecode + ProxyPass / http://localhost:8080/ nocanon + ProxyPassReverse / http://localhost:8080/ + SSLCertificateFile /etc/letsencrypt/live/trilium.yourdomain.com/fullchain.pem + SSLCertificateKeyFile /etc/letsencrypt/live/trilium.yourdomain.com/privkey.pem + Include /etc/letsencrypt/options-ssl-apache.conf + + ``` + + 4. Enable the virtual host with `sudo a2ensite trilium.yourdomain.com.conf` + + 5. Reload apache2 with `sudo systemctl reload apache2` + +3. Create and enable a systemd service to start the docker container on boot + + 1. Create a new empty file called `/lib/systemd/system/trilium.service` with the contents + + ```text-plain + [Unit] + Description=Trilium Server + Requires=docker.service + After=docker.service + + [Service] + Restart=always + ExecStart=/usr/bin/docker start -a trilium + ExecStop=/usr/bin/docker stop -t 2 trilium + + [Install] + WantedBy=local.target + ``` + + 2. Install, enable and start service + + ```text-plain + sudo systemctl daemon-reload + sudo systemctl enable trilium.service + sudo systemctl start trilium.service + ``` diff --git a/Wiki/archived-notes.md b/Wiki/archived-notes.md new file mode 100644 index 0000000..55eb5c5 --- /dev/null +++ b/Wiki/archived-notes.md @@ -0,0 +1,10 @@ +# Archived-notes +Archived notes are notes which have `archived` [attribute](attributes.md) - either directly or [inherited](attribute-inheritance.md). + +Such notes are then by default not shown in the autocomplete and in the full text [search](search.md). + +This can be useful for notes which are no longer very useful but still valuable enough to keep around without them getting too much in the way. + +You can control whether archived notes are displayed in the note tree with a setting: + +![](images/hide-archived.png) diff --git a/Wiki/attachments.md b/Wiki/attachments.md new file mode 100644 index 0000000..86440f6 --- /dev/null +++ b/Wiki/attachments.md @@ -0,0 +1,8 @@ +# Attachments +A note can _own_ one or more attachments. The attachment is either an image or file which can be displayed/linked in the note which owns it. + +The note is the exclusive owner of its attachments - they can't be linked from other notes. If a user copies the attachment link from one note to another, the attachment itself is copied and from then on lives an independent life. + +Attachments is a feature available in Trilium since v0.61. Attachment is now a preferred way to include images into notes. Previously, an image had to be an independent note which could be then displayed in multiple notes, but this approach proved to be complicated. Image as notes still remains as an option, and is a more suitable choice in some cases (e.g. when the particular image is sort of standalone). It is possible to convert an image to an attachment and vice versa. + +Image attachments are expected to be linked in the owning text note. If it's not linked, it will get deleted in a configurable timeout. diff --git a/Wiki/attribute-inheritance.md b/Wiki/attribute-inheritance.md new file mode 100644 index 0000000..05f25a5 --- /dev/null +++ b/Wiki/attribute-inheritance.md @@ -0,0 +1,21 @@ +# Attribute inheritance +Standard inheritance +-------------------- + +Every [attribute](attributes.md) has flag called `isInheritable`. If this is true, then this attribute (key-value) is also applied to all its children notes, children's children notes etc. + +Example how this might be useful is `archived` label which hides its note from Jump to / Add link dialogs. Often times you want to archive some specific subtree, you can do this by making the `archived` label inheritable. + +Copying inheritance +------------------- + +A different kind of inheritance is achieved using `child:` attribute name prefix. We can define that when a note is created under a certain parent note then the new child note will automatically receive defined attributes. The difference from standard inheritance is that these are real new attributes which are completely independent of the parent and will be therefore kept even if the note is moved elsewhere in the note tree. + +For defining the copy-attributes we use `child:` prefix in attribute name, the rest is defined normally. So as an example, when we create a child note in a note with `#child:exampleAttribute` label, then the child note will have `#exampleAttribute` label. This can be even chained, e.g. `#child:child:exampleAttribute`, in this case `#child:exampleAttribute` will be created in the child and `#exampleAttribute` will be created in the child of the child. + +Which kind of attribute inheritance (or if any at all) should be used depends on the specific use case. + +Template inheritance +-------------------- + +[Attribute template](template.md) could be also seen as a form of inheritance. diff --git a/Wiki/attributes.md b/Wiki/attributes.md new file mode 100644 index 0000000..7e7b3cb --- /dev/null +++ b/Wiki/attributes.md @@ -0,0 +1,114 @@ +# Attributes +Note attributes are key-value records owned by (assigned to) given note. + +There are 2 types of attributes: + +* Labels - simple key-value text record +* Relation - specifies named relation (link) to another note + +Sometimes we're talking about labels and relations - keep in mind that both of them are types of attributes. + +![](images/attributes.png) + +Labels +------ + +Labels can be used for several things: + +* as labels with optional value - e.g. when cataloguing books, you might add labels like #year=1999, #genre="sci-fi", #author="Neal Stephenson" +* attributes can be used to configure some advanced features / settings - see below +* plugins / scripts can use these to mark notes with some special values / metadata (e.g. [Weight Tracker](weight-tracker.md) will have "weight" attribute on [day notes](day-notes.md) based on whose it can create chart). + +Labels can be used for [searching](search.md). + +### Standard labels + +The following labels are used for advanced configuration: + +* `disableVersioning` - disables auto-versioning. Useful for e.g. large, but unimportant notes - e.g. large JS libraries used for scripting +* `calendarRoot` - marks note which should be used as root for [day notes](day-notes.md). Only one should be marked as such. +* `archived` - notes with this label won't be visible by default in search results (also in Jump To, Add Link dialogs etc). +* `excludeFromExport` - notes (with their sub-tree) won't be included in any note export. +* `run` - defines on which events script should run. Possible values are: + * `frontendStartup` - when Trilium frontend starts up (or is refreshed). + * `backendStartup` - when Trilium backend starts up. + * `hourly` - run once an hour. You can use additional label `runAtHour` to specify at which hour. + * `daily` - run once a day. +* `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. +* `runOnInstance` - define which trilium instance this should run on. Defaults to all instances. +* `disableInclusion` - scripts with this label won't be included into parent script execution. +* `sorted` - keeps child notes sorted (by title, alphabetically. See [Sorting](sorting.md)). +* `top` - keeps this note at the top of the list within its parent (applies only on parents with `sorted` attribute). +* `hidePromotedAttributes` - hide promoted attributes on this note. +* `readOnly` - editor is in read only mode. Works only for text and code notes. See some use cases [here](https://github.com/TriliumNext/Notes/issues/371). +* `autoReadOnlyDisabled` - text/code notes can be set automatically into read mode when they are too large. You can disable this behavior on per-note basis by adding this label to the note +* `appCss` - marks CSS notes which are loaded into the Trilium application and can thus be used to modify Trilium's looks. +* `appTheme` - marks CSS notes which are full Trilium themes and are thus available in Trilium options. +* `cssClass` - the value of this label is then added as CSS class to the node representing the given note in the tree. This can be useful for advanced [themes](themes.md). Can be used in `template` notes. +* `iconClass` - the value of this label is added as a CSS class to the icon on the tree, which can help visually distinguish the notes in the tree. An example might be `bx bx-home` - icons are taken from [boxicons](https://boxicons.com/). Can be used in [template](template.md) notes. +* `pageSize`\- number of items per page in note listing. +* `customRequestHandler` and `customResourceProvider` - see [Custom request handler](custom-request-handler.md) +* `widget` - marks this note as a custom widget, which will be added to the Trilium component tree. See [Custom widget](custom-widget.md). +* `workspace`, `workspaceIconClass`, `workspaceTabBackgroundColor`, `workspaceCalendarRoot` - see [Workspace](workspace.md) +* `searchHome` - new search notes will be created as children of this note (otherwise they are created in [Day notes](day-notes.md)) +* `hoistedSearchHome` - new search notes will be created as children of this note when hoisted to some ancestor of this note +* `inbox` - default inbox location for new notes - when you create a note using "new note" button in the sidebar, notes will be created as child notes in the note marked as with `#inbox` label. +* `hoistedInbox` - default inbox location for new notes when hoisted to some ancestor of this note +* `sqlConsoleHome` - default location of SQL console notes +* `bookmarked` and `bookmarkFolder` - see [Bookmarks](bookmarks.md) +* `shareXXX` labels - see [Sharing](sharing.md) +* `keyboardShortcut` - can be defined as e.g. "Ctrl+I". Pressing this keyboard combination will then bring you to the note on which it is defined. Note that Trilium must be reloaded/restarted (Ctrl+R) for changes to be in effect. +* `displayRelations` and `hideRelations` - comma delimited names of relations which should be displayed/hidden. All other relations will be hidden/visible. +* `hideRelations` - comma delimited names of relations which should be hidden. +* `titleTemplate` - see [Default note title](default-note-title.md). +* `template` - this note will appear in the selection of available templates when creating new notes. +* `toc` - `#toc` or `#toc=show` will force the table of contents to be shown, `#toc=hide` will force hiding it. +* `color` - defines the color of the note in links, tree etc. Use any valid CSS value like `red` or `#f0a349` +* `hideChildrenOverview` - Hides child notes from being displayed in the editor of the parent note +* `viewType` - Allows setting the view of the child notes inside the editor to a grid or list. Possible values: + * `grid` - displays child notes in a grid + * `list` - displays child notes in a list + +Relations +--------- + +Relation is a kind of link between two notes. + +This could be used when you e.g. keep a book database, you can use relations to keep formal links between the book (note) and the book's author (note) by defining an "author" relation on the book note pointing to the author's note. + +Relations are used also for some advanced scripting - like attaching scripts to events happening on certain note. + +### Standard relations + +[Events](events.md): + +* `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. +* `runOnChildNoteCreation` - executes when new note is created under the note where this relation is defined +* `runOnNoteTitleChange` - executes when note title is changed (includes note creation as well) +* `runOnNoteChange` - executes when note is changed (includes note creation as well) +* `runOnNoteDeletion` - executes when note is being deleted. +* `runOnBranchCreation` and `runOnBranchDeletion` - executes when a branch is created/deleted. Branches are links between a parent and a child note, and are created when e.g. cloning or moving notes. +* `runOnAttributeCreation` - executes when new attribute is created for the note which defines this relation +* `runOnAttributeChange` - executes when the attribute is changed of a note which defines this relation. This is triggered also when the attribute is deleted + +Other relations: + +* `template` - attached note's attributes will be inherited even without parent-child relationship. See [template](template.md) for details. +* `renderNote` - notes of type "render HTML note" will be rendered using a code note (HTML or script) and it is necessary to point using this relation to which note should be rendered +* `widget` - target of this relation will be executed and rendered as a widget in the sidebar +* `shareXXX` relations described in [Sharing](sharing.md) + +Multiplicity +------------ + +Attributes allow multiplicity - there can be multiple attributes with the same name. We're then calling such attributes "multivalued". + +Attribute definitions / promoted attributes +------------------------------------------- + +Special kind of labels are used to create "label/attribute" definitions. See [Promoted attributes](promoted-attributes.md) for details. + +Attribute inheritance +--------------------- + +See [Attribute inheritance](attribute-inheritance.md). diff --git a/Wiki/backup.md b/Wiki/backup.md new file mode 100644 index 0000000..08382c7 --- /dev/null +++ b/Wiki/backup.md @@ -0,0 +1,43 @@ +# Backup +Trilium supports simple backup scheme where it saves copy of the [document](document.md) on these events: + +* once a day +* once a week +* once a month +* before DB migration to newer version + +So in total you'll have at most 4 backups from different points in time which should protect you from various problems. These backups are stored by default in `backup` directory placed in the [data directory](data-directory.md). + +This is only very basic backup solution, and you're encouraged to add some better backup solution - e.g. backing up the [document](document.md) to cloud / different computer etc. + +Note that [synchronization](synchronization.md) provides also some backup capabilities by its nature of distributing the data to other computers. + +Restoring backup +---------------- + +Let's assume you want to restore the weekly backup, here's how to do it: + +* find [data directory](data-directory.md) Trilium uses - easy way is to open "About Trilium Notes" from "Menu" in upper left corner and looking at "data directory" + * I'll refer to `~/trilium-data` as data directory from now on +* find `~/trilium-data/backup/backup-weekly.db` - this is the [document](document.md) backup +* at this point stop/kill Trilium +* delete `~/trilium-data/document.db`, `~/trilium-data/document.db-wal` and `~/trilium-data/document.db-shm` (latter two files are auto generated) +* copy and rename this `~/trilium-data/backup/backup-weekly.db` to `~/trilium-data/document.db` +* make sure that the file is writable, e.g. with `chmod 600 document.db` +* start Trilium again + +If you have configured sync then you need to do it across all members of the sync cluster, otherwise older version (restored backup) of the document will be detected and synced to the newer version. + +Disabling backup +---------------- + +Although this is not recommended, it is possible to disable backup in `config.ini` in the [data directory](data-directory.md): + +```text-plain +[General] +... some other configs +# set to true to disable backups (e.g. because of limited space on server) +noBackup=true +``` + +See [sample config](https://github.com/TriliumNext/Notes/blob/master/config-sample.ini). %%{WARNING}%% diff --git a/Wiki/book-note.md b/Wiki/book-note.md new file mode 100644 index 0000000..3f37a0f --- /dev/null +++ b/Wiki/book-note.md @@ -0,0 +1,10 @@ +# Book note +Book [note](note.md) is a type of note which displays all its children's content in a linear fashion, so you can read note subtree like a book. This can be useful for reading many smaller notes. Seeing an example might explain this concept better: + +![](images/book-note.png) + +Notice in the tree on the left pane how "node.js" note has some children and these are then displayed on the right pane. + +You can also switch to "grid view" in the Book properties: + +![](images/book-note-pictures.png) diff --git a/Wiki/bookmarks.md b/Wiki/bookmarks.md new file mode 100644 index 0000000..99ff9e2 --- /dev/null +++ b/Wiki/bookmarks.md @@ -0,0 +1,13 @@ +# Bookmarks +To easily access selected notes, you can bookmark them. See demo: + +![](images/bookmarks.gif) + +Bookmark folder +--------------- + +Space in the left panel is limited, and you might want to bookmark many items. One possible solution is to bookmark a folder, so it shows its children: + +![](images/bookmark-folder.png) + +To do this, you need to add a `#bookmarkFolder` label to the note. diff --git a/Wiki/canvas-note.md b/Wiki/canvas-note.md new file mode 100644 index 0000000..a834f28 --- /dev/null +++ b/Wiki/canvas-note.md @@ -0,0 +1,6 @@ +# Canvas-note +(Since trilium v0.52) + +Canvas note use the excalidraw library to allow handwritten notes with mouse, pen or touch on an infinite canvas. It also supports basic diagramming, text and garphics input. + +![grafik](images/Canvas-note%20image.png) diff --git a/Wiki/cloning-notes.md b/Wiki/cloning-notes.md new file mode 100644 index 0000000..467c94a --- /dev/null +++ b/Wiki/cloning-notes.md @@ -0,0 +1,70 @@ +# Cloning notes +Motivation +---------- + +Trilium's core feature is the ability to structure your notes into hierarchical tree-like structure. + +It is expected then that you'll have an elaborate and deep note hierarchy - each subtree will represent a more refined and specialized view of your knowledge base. + +This is a pretty powerful approach, but it also carries a hidden assumption that each "subtopic" is "owned" by one parent. I'll illustrate this with an example - let's say my basic structure is this: + +* Technology + * Programming + * Kotlin + * JavaScript + * Operating systems + * Linux + * Windows + +Now, I'm starting to learn about [Bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)) and would like to create notes related to this topic. But now I'm facing a problem of where to categorize this. The issue here is that Bash is both a programming language and a tool (shell) very much tied into Linux. It seems it belongs to both of these, I can't (and don't want to) choose one over the other. + +Solution +-------- + +The solution to the problem shown above is to allow notes to have multiple parents. + +I call these "clones", but that is a bit misleading - there's no original and cloned note - the notes in both of the parents categories are identical. + +Another misleading thing about "cloning" is that it suggests that a copy of the note has been made. That's not really true, the note itself stays in just one original, it is just referenced in multiple places in the tree hierarchy. So changing it in one category changes it in all the others, because they're all the same note. + +Here's the final structure with cloning: + +* Technology + * Programming + * Kotlin + * JavaScript + * Bash + * some sub-notes ... + * Operating systems + * Linux + * Bash + * some sub-notes ... + * Windows + +So now the "Bash" subtree appears on multiple locations in the hierarchy. Both the Bash subtrees are the same and contain the same sub-categories and notes. + +### Demo + +![](images/create-clone.gif) + +In the demo, you can see how a clone can be created using the context menu. It's possible to do this also using the Add Link dialog or with CTRL+C and CTRL+V [keyboard shortcuts](keyboard-shortcuts.md). + +As seen in the demo, you can view the list of all available clones in the "Note Paths" tab in the Ribbon toolbar. + +Titles of cloned notes in the tree view have an asterisk to the right to easily see that the note is also placed into some other location. + +Prefix +------ + +Since notes can be categorized into multiple places, it's recommended to choose a generalized name that fits into all locations instead of something more specific to avoid confusion. In some cases this isn't possible so Trilium provides "branch prefixes", which is shown before the note name in the tree and as such provides a specific kind of context. The prefix is location specific, so it's displayed only in the tree pane. + +Deleting notes/clones +--------------------- + +With clones, it might not be immediately obvious how deleting works. + +If you try to delete a note, it works like this: + +1. if the note has multiple clones, delete just this clone and leave the actual note (and its other clones) as it is. +2. if this note doesn't have any other clones, delete the note + * Run the whole process starting with 1. on all note's children notes diff --git a/Wiki/code-notes.md b/Wiki/code-notes.md new file mode 100644 index 0000000..2b289f3 --- /dev/null +++ b/Wiki/code-notes.md @@ -0,0 +1,23 @@ +# Code-notes +Trilium supports creating "code" notes, i.e. notes which contain some sort of formal code - be it programming language (C++, JavaScript), structured data (JSON, XML) or other types of codes (CSS etc.). + +This can be useful for a few things: + +* computer programmers can store code snippets as notes with syntax highlighting +* JavaScript code notes can be executed inside Trilium for some extra functionality + * we call such JavaScript code notes "scripts" - see [Scripts](scripts.md) +* JSON, XML etc. can be used as storage for structured data (typically used in conjunction with scripting) + +![](images/code-note.png) + +Extra languages +--------------- + +Trilium supports syntax highlighting for many languages, but by default displays only some of them (to reduce the number of items). You can add extra languages in Options -> Code notes. + +Code blocks +----------- + +An alternative to the code note is a "code block" - feature of a text note which can add short snippets of code to the text editor. The disadvantage is that code blocks don't support syntax highlighting. + +![](images/code-block.png) diff --git a/Wiki/custom-request-handler.md b/Wiki/custom-request-handler.md new file mode 100644 index 0000000..2adca1a --- /dev/null +++ b/Wiki/custom-request-handler.md @@ -0,0 +1,93 @@ +# Custom request handler +Trilium provides a mechanism for [scripts](scripts.md) to open a public REST endpoint. This opens a way for various integrations with other services - a simple example would be creating new note from Slack by issuing a slash command (e.g. `/trilium buy milk`). + +Create note from outside Trilium +-------------------------------- + +Let's take a look at an example. The goal is to provide a REST endpoint to which we can send title and content and Trilium will create a note. + +We'll start with creating a JavaScript backend [code note](code-notes.md) containing: + +```text-plain +const {req, res} = api; +const {secret, title, content} = req.body; + +if (req.method == 'POST' && secret === 'secret-password') { + // notes must be saved somewhere in the tree hierarchy specified by a parent note. + // This is defined by a relation from this code note to the "target" parent note + // alternetively you can just use constant noteId for simplicity (get that from "Note Info" dialog of the desired parent note) + const targetParentNoteId = api.currentNote.getRelationValue('targetNote'); + + const {note} = api.createTextNote(targetParentNoteId, title, content); + const notePojo = note.getPojo(); + + res.status(201).json(notePojo); +} +else { + res.send(400); +} +``` + +This script note has also following two attributes: + +* label `#customRequestHandler` with value `create-note` +* relation `~targetNote` pointing to a note where new notes should be saved + +### Explanation + +Let's test this by using an HTTP client to send a request: + +```text-plain +POST http://my.trilium.org/custom/create-note +Content-Type: application/json + +{ + "secret": "secret-password", + "title": "hello", + "content": "world" +}+++++++++++++++++++++++++++++++++++++++++++++++ +``` + +Notice the `/custom` part in the request path - Trilium considers any request with this prefix as "custom" and tries to find a matching handler by looking at all notes which have `customRequestHandler` [label](attributes.md). Value of this label then contains a regular expression which will match the request path (in our case trivial regex "create-note"). + +Trilium will then find our code note created above and execute it. `api.req`, `api.res` are set to [request](https://expressjs.com/en/api.html#req) and [response](https://expressjs.com/en/api.html#res) objects from which we can get details of the request and also respond. + +In the code note we check the request method and then use trivial authentication - keep in mind that these endpoints are by default totally unauthenticated, and you need to take care of this yourself. + +Once we pass these checks we will just create the desired note using [Script API](script-api.md). + +Custom resource provider +------------------------ + +Another common use case is that you want to just expose a file note - in such case you create label `customResourceProvider` (value is again path regex). + +Note: The file that is supposed to be exposed needs to have a label `#customResourceProvider="fonts/myFont.woff` + +For example, your file is in custom/fonts, you can call it via `custom/fonts/myFont.woff`. + +Advanced concepts +----------------- + +`api.req` and `api.res` are Express.js objects - you can always look into its [documentation](https://expressjs.com/en/api.html) for details. + +### Parameters + +REST request paths often contain parameters in the URL, e.g.: + +```text-plain +http://my.trilium.org/custom/notes/123 +``` + +The last part is dynamic so the matching of the URL must also be dynamic - for this reason the matching is done with regular expressions. Following `customRequestHandler` value would match it: + +```text-plain +notes/([0-9]+) +``` + +Additionally, this also defines a matching group with the use of parenthesis which then makes it easier to extract the value. The matched groups are available in `api.pathParams`: + +```text-plain +const noteId = api.pathParams[0]; +``` + +Often you also need query params (as in e.g. `http://my.trilium.org/custom/notes?noteId=123`), you can get those with standard express `req.query.noteId`. diff --git a/Wiki/custom-widget.md b/Wiki/custom-widget.md new file mode 100644 index 0000000..6a89565 --- /dev/null +++ b/Wiki/custom-widget.md @@ -0,0 +1,97 @@ +# Custom-widget +It's possible to create custom widget in three possible locations where you can display your custom content. + +Positions are: + +* `left-pane` +* `center-pane` +* `note-detail-pane` - located within `center-pane`, but specific to note (split) +* `right-pane` + +Example - word count widget +--------------------------- + +Create a code note of type JS frontend and **give it a** `**#widget**` **label**. + +```text-plain +/* + * This defines a custom widget which displays number of words and characters in a current text note. + * To be activated for a given note, add label 'wordCount' to the note, you can also make it inheritable and thus activate it for the whole subtree. + * + * See it in action in "Books" and its subtree. + */ +const TPL = `
+ Word count: + + +   + + Character count: + +
`; + +class WordCountWidget extends api.NoteContextAwareWidget { + static get parentWidget() { return 'center-pane'; } + + get position() { return 100; } // higher value means position towards the bottom/right + + isEnabled() { + return super.isEnabled() + && this.note.type === 'text' + && this.note.hasLabel('wordCount'); + } + + doRender() { + this.$widget = $(TPL); + this.$wordCount = this.$widget.find('.word-count'); + this.$characterCount = this.$widget.find('.character-count'); + return this.$widget; + } + + async refreshWithNote(note) { + const {content} = await note.getNoteComplement(); + + const text = $(content).text(); // get plain text only + + const counts = this.getCounts(text); + + this.$wordCount.text(counts.words); + this.$characterCount.text(counts.characters); + } + + getCounts(text) { + const chunks = text + .split(/[\s-+:,/\\]+/) + .filter(chunk => chunk !== ''); + + let words; + + if (chunks.length === 1 && chunks[0] === '') { + words = 0; + } + else { + words = chunks.length; + } + + const characters = chunks.join('').length; + + return {words, characters}; + } + + async entitiesReloadedEvent({loadResults}) { + if (loadResults.isNoteContentReloaded(this.noteId)) { + this.refresh(); + } + } +} + +module.exports = WordCountWidget; +``` + +After you make changes it is necessary to restart Trilium so that the layout can be rebuilt. + +### Example screenshot + +On the bottom you can see the resulting widget: + +![](images/Custom-widget%20image.png) diff --git a/Wiki/data-directory.md b/Wiki/data-directory.md new file mode 100644 index 0000000..7d396aa --- /dev/null +++ b/Wiki/data-directory.md @@ -0,0 +1,89 @@ +# Data-directory +Data directory contains: + +* `document.db` - [document](document.md) +* `config.ini` - instance level settings like port on which the Trilium application runs +* `backup` - contains automatically [backup](backup.md) of documents +* `log` - contains application log files + +Location +-------- + +Easy way how to find out which data directory Trilium uses is to look at the "About Trilium Notes" dialog (from "Menu" in upper left corner): + +![](images/about-trilium-data-dir.png) + +Here's how the location is decided: + +Data directory is normally named `trilium-data` and it is stored in: + +* `/home/[user]/.local/share` for Linux +* `C:\Users\[user]\AppData\Roaming` for Windows Vista and up +* `/Users/[user]/Library/Application Support` for Mac OS +* user's home is a fallback if some of the paths above don't exist +* user's home is also a default setup for \[\[docker|Docker server installation\]\] + +If you want to back up your Trilium data, just backup this single directory - it contains everything you need. + +### Changing the location of data directory + +If you want to use some other location for the data directory than the default one, you may change it via TRILIUM\_DATA\_DIR environment variable to some other location: + +#### Linux + +```text-plain +export TRILIUM_DATA_DIR=/home/myuser/data/my-trilium-data +``` + +#### Mac OS X + +You need to create a .plist file under `~/Library/LaunchAgents` to load it properly each login. + +To load it manually, u need to use `launchctl setenv TRILIUM_DATA_DIR ` + +Here is a pre-defined template, where you just need to add your path to: + +```text-plain + + + + + + Label + set.trilium.env + RunAtLoad + + ProgramArguments + + launchctl + setenv + TRILIUM_DATA_DIR + /Users/YourUserName/Library/Application Support/trilium-data + + + +``` + +### Create a script to run with specific data directory + +An alternative to globally setting environment variable is to run only the Trilium Notes with this environment variable. This then allows for different setup styles like two [document](document.md) instances or "portable" installation. + +To do this in unix based systems simply run trilium like this: + +```text-plain +TRILIUM_DATA_DIR=/home/myuser/data/my-trilium-data trilium +``` + +You can then save the above command as a shell script on your path for convenience. + +### Fine-grained directory/path location + +It's possible to configure e.g. backup and log directories separately, with following env. variables: + +* `TRILIUM_DOCUMENT_PATH` +* `TRILIUM_BACKUP_DIR` +* `TRILIUM_LOG_DIR` +* `TRILIUM_ANONYMIZED_DB_DIR` +* `TRILIUM_CONFIG_INI_PATH` + +If these are not set, default paths within the data directory will be used. diff --git a/Wiki/day-notes.md b/Wiki/day-notes.md new file mode 100644 index 0000000..4b5f233 --- /dev/null +++ b/Wiki/day-notes.md @@ -0,0 +1,62 @@ +# Day-notes +A common pattern in note-taking is that a lot of notes will be centered around a certain date - e.g. you have some tasks which needs to be done on a certain date, you have meeting minutes from a certain date, you have your thoughts etc. and it all revolves around a date on which they occurred. For this reason, it makes sense to create a certain "day workspace" which will centralize all those notes relevant for a certain date. + +For this, Trilium provides a concept of "day note". Trilium semi-automatically generates a single note for each day. Under this note you can save all those relevant notes. + +Select an existing day note, and the menubar contains a calendar widget. Select any day to create a note for that day. ![image](images/Day-notes%20image.png) + +This pattern works well also because of \[\[cloning|Cloning notes\]\] functionality - note can appear in multiple places in the note tree, so besides appearing under day note, it can also be categorized into other notes. + +Demo +---- + +![](images/day-notes.png) + +You can see the structure of day notes appearing under "Journal" note - there's a note for the whole year 2017, under it, you have "12 - December" which then contains "18 - Monday". This is our "day note" which contains some text in its content and also has some child notes (some of them are from [Task manager](task-manager.md)). + +You can also notice how this day note has [promoted attribute](promoted-attributes.md) "weight" where you can track your daily weight. This data is then used in [Weight tracker](weight-tracker.md). + +Templates +--------- + +Trilium provides [template](template.md) functionality, and it could be used together with day notes. + +You can define one of the following relations on the root of the journal (identified by `#calendarRoot` label): + +* yearTemplate +* monthTemplate +* dateTemplate + +All of these are relations. When Trilium creates a new note for year or month or date, it will take a look at the root and attach a corresponding `~template` relation to the newly created role. Using this, you can e.g. create your daily template with e.g. checkboxes for daily routine etc. + +Date pattern +------------ + +It's possible to customize the title of generated date notes by defining a `#datePattern` label on a root calendar note (identified by `#calendarRoot` label). Following are possible values: + +* `{dayInMonthPadded} - {weekDay}` day notes are named e.g. "24 - Monday" +* `{dayInMonthPadded}: {weekDay3}` day notes are named e.g. "24: Mon" +* `{dayInMonthPadded}: {weekDay2}` day notes are named e.g. "24: Mo" +* `{isoDate} - {weekDay}` day notes are named e.g. "2020-12-24 - Monday" +* `{ordinal}` is replaced with the ordinal date (e.g. 1st, 2nd, 3rd) etc. + +Month pattern +------------- + +It is also possible to customize the title of generated month notes through the `#monthPattern` attribute, much like `#datePattern`. The options are: + +* `{monthNumberPadded}` results in a number like `09` for September, and `11` for November +* `{month}` results in the full month name (e.g. `September` or `October`) +* `{shortMonth3}` is replaced with the first 3 letters of the month, e.g. Jan, Feb, etc. +* `{shortMonth4}` is replaced with the first 4 letters of the month, e.g. Sept, Octo, etc. + +The default is `{monthNumberPadded} - {month}` + +Implementation +-------------- + +Trilium has some special support for day notes in the form of [backend Script API](https://zadam.github.io/trilium/backend_api/BackendScriptApi.html) - see e.g. getDayNote() function. + +Day (and year, month) notes are created with a label - e.g. `#dateNote="2018-08-16"` this can then be used by other scripts to add new notes to day note etc. + +Journal also has relation `child:child:child:template=Day template` (see \[\[attribute inheritance\]\]) which effectively adds \[\[template\]\] to day notes (grand-grand-grand children of Journal). diff --git a/Wiki/default-note-title.md b/Wiki/default-note-title.md new file mode 100644 index 0000000..2dbe0da --- /dev/null +++ b/Wiki/default-note-title.md @@ -0,0 +1,31 @@ +# Default-note-title +When a new note is created, its name is by default "new note". In some cases, it can be desirable to have a different or even a dynamic default note title. + +For this use case, Trilium (since v0.52) supports `#titleTemplate` [label](attributes.md). You can create such a label for a given note, assign it a value, and this value will be used as a default title when creating child notes. As with other labels, you can make it inheritable to apply recursively, and you can even place it on the root note to have it applied globally everywhere. + +As an example use case, imagine you collect books you've read in a given year like this: + +* 2022 Books + * Neal Stephenson: Anathem, 2008 + * Franz Kafka: Die Verwandlung, 1915 + +Now, to the parent note "2022 Books" you can assign label `#titleTemplate="[Author name]: [Book title], [Publication year]"`. + +And all children of "2022 Books" will be created with initial title "\[Author name\]: \[Book title\], \[Publication year\]". There's no artificial intelligence here, the idea is to just prompt you to manually fill in the pieces of information into the note title by yourself. + +Dynamic value +------------- + +The value of `#titleTemplate` is evaluated at the point of note's creation as a JavaScript string, which means it can be enriched with the help of JS string interpolation with dynamic data. + +As an example, imagine you collect server outage incidents and write some notes. It looks like this: + +* Incidents + * 2022-05-09: System crash + * 2022-05-15: Backup delay + +You can automatize the date assignment by assigning a label `#titleTemplate="${now.format('YYYY-MM-DD')}: "` to the parent note "Incidents". Whenever a new child note is created, the title template is evaluated with the injected [now](https://day.js.org/docs/en/display/format) object. + +Second variable injected is [parentNote](https://zadam.github.io/trilium/backend_api/Note.html), an example could be `#titleTemplate="${parentNote.getLabelValue('authorName')}'s literary works"`. + +See also \[\[[template](template.md)\]\] which provides similar capabilities, including default note's content. diff --git a/Wiki/desktop-installation.md b/Wiki/desktop-installation.md new file mode 100644 index 0000000..e6c86c8 --- /dev/null +++ b/Wiki/desktop-installation.md @@ -0,0 +1,17 @@ +# Desktop-installation +If you want to use Trilium on the desktop, download binary release for your platform from [latest release](https://github.com/TriliumNext/Notes/releases/latest), unzip the package and run `trilium` executable. + +Startup scripts +--------------- + +There are also some other options to start Trilium: + +* `trilium-no-cert-check` - Trilium will not validate the certificates, useful e.g. when you're syncing against a sync server with self-signed certificate + * Alternatively you can set `NODE_TLS_REJECT_UNAUTHORIZED=0` environment variable to the Trilium process. +* `trilium-portable` - Trilium will try to create [data directory](data-directory.md) in the trilium's directory +* `trilium-safe-mode` - start up in "safe mode" which disables any startup scripts which might e.g. crash the application + +Synchronization +--------------- + +If you are using a desktop instance and would like to sync with your server instance: [Synchronization](synchronization.md) diff --git a/Wiki/docker-server-installation.md b/Wiki/docker-server-installation.md new file mode 100644 index 0000000..de87c66 --- /dev/null +++ b/Wiki/docker-server-installation.md @@ -0,0 +1,93 @@ +# Docker-server-installation +Trilium can be run as docker image. This is recommended way to deploy Trilium on servers. + +Official docker images are published on docker hub for **AMD64**, **ARMv6**, **ARMv7** and **ARMv8/64**: [https://hub.docker.com/r/zadam/trilium/](https://hub.docker.com/r/zadam/trilium/)%%{WARNING}%% + +Prerequisites +------------- + +To start, you will need to have docker installed on your computer. Here are two guides that can help: + +* [https://docs.docker.com/engine/install/ubuntu/](https://docs.docker.com/engine/install/ubuntu/) +* [https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04) + +Trilium docker container requires running as root, check if this is possible in your environment. + +Pull image +---------- + +```text-plain +docker pull zadam/trilium:[VERSION] %%{WARNING}%% +``` + +Replace \[VERSION\] for actual latest version or use "series" tag - e.g. `0.52-latest`. + +**It's not recommended to use "latest" tag since it may upgrade your Trilium instance to a new minor version, which may potentially break your sync setup or cause other issues.** + +Prepare data directory on the host system +----------------------------------------- + +Trilium needs a directory where it can store its data, this then needs to be mounted into the docker container. The container needs to runs as a root to be able to access it in write mode. + +Run image +--------- + +These commands mount the volume to the host system so that trilium's data (most importantly [document](document.md)) is persisted and not cleared after container stops. + +### Local only + +This will run the container so that it only available on the localhost. Use this to test the installation from a web browser on the same machine you run this command on, or if you are using a proxy with nginx/apache. + +```text-plain +sudo docker run -t -i -p 127.0.0.1:8080:8080 -v ~/trilium-data:/home/node/trilium-data zadam/trilium:[VERSION] %%{WARNING}%% +``` + +1. Test to see that the docker image is running with `docker ps` +2. Access the trilium by opening a browser and go to `127.0.0.1:8080` + +### Local network only + +This command will run the container so that it is only available on your local network. This is preferable if you do not want to open ports to the rest of the internet. However, you can still access it from outside by using a VPN like WireGuard to get into your own network first. This method does assume that your local network limits outside access. + +First, you have to create a new network in Docker to access your local network. Here is an example, give note to "parent" and the network numbers as it may differ from your own. For more detailed information, [click here](https://blog.oddbit.com/post/2018-03-12-using-docker-macvlan-networks/). + +```text-plain +docker network create -d macvlan -o parent=eth0 --subnet 192.168.2.0/24 --gateway 192.168.2.254 --ip-range 192.168.2.252/27 mynet +``` + +Secondly, you have to adjust the docker run command so it takes this network into account but keep using localhost to limit the accessibility of the ports to the outside world. + +```text-plain +docker run --net=mynet -d -p 127.0.0.1:8080:8080 -v ~/trilium-data:/home/node/trilium-data zadam/trilium:0.52-latest +``` + +Alternatively, if you wish to have the saved data and the application using a different UID & GID than 1000:1000, you can use the USER\_UID & USER\_GID environment variables: + +```text-plain +docker run --net=mynet -d -p 127.0.0.1:8080:8080 -e "USER_UID=1001" -e "USER_GID=1001" -v ~/trilium-data:/home/node/trilium-data zadam/trilium:0.52-latest %%{WARNING}%% +``` + +Finally, use docker inspect to find your local IP address to connect to. You can access this from all your devices connected to the local network as such: \[local:ip\]:8080. + +```text-plain +docker ps +docker inspect [container_name] +``` + +### Available anywhere + +This will run the container as a background process and will be available from any IP address + +```text-plain +docker run -d -p 0.0.0.0:8080:8080 -v ~/trilium-data:/home/node/trilium-data zadam/trilium:[VERSION] %%{WARNING}%% +``` + +To stop this background docker process use `docker ps` to get the "CONTAINER ID" and then use `docker stop ` + +### Different data directory location + +If you want to run your instance in a non-default way, please use the volume switch as follows: `-v ~/YourOwnDirectory:/home/node/trilium-data zadam/trilium:[VERSION]`. It is important to be aware of how Docker works for volumes, with the first path being your own and the second the one to virtually bind to. [https://docs.docker.com/storage/volumes/](https://docs.docker.com/storage/volumes/) + +### Note about --user directive + +Please note, the --user directive is not supported and the container will not run without root. Instead please use the USER\_UID & USER\_GID environment variables as shown above. diff --git a/Wiki/document.md b/Wiki/document.md new file mode 100644 index 0000000..7c03f94 --- /dev/null +++ b/Wiki/document.md @@ -0,0 +1,46 @@ +# Document +Document is [SQLite](https://www.sqlite.org) database which contains all notes, tree structure, metadata and most of the configuration. + +Location +-------- + +Document is stored in the [data directory](data-directory.md). + +Demo document +------------- + +When you run Trilium for the first time, it will generate a demo document for you as a starting point. It's also pretty useful for demonstration of some of Trilium's features, e.g.: + +* [Relation map](relation-map.md) +* [Day notes](day-notes.md) +* [Weight tracker](weight-tracker.md) +* [Task manager](task-manager.md) +* [Custom CSS theme](themes.md) + +### Restoring demo document + +In some cases you might want to take a look at the demo document after you deleted it. Or you might want to see if there was something added (sometimes we add a new feature demonstration into demo document). In such case you can just [download .zip archive](https://github.com/TriliumNext/Notes/raw/stable/db/demo.zip) %%{WARNING}%% of the latest document and import it somewhere into the tree (right-click on a note where you want to import the demo document and choose "Import"). + +Manually modifying the document +------------------------------- + +Trilium provides a lot of flexibility, but with that you can also potentially shoot yourself in the foot (e.g. with startup script which blanks the app view). + +In such cases you can manually fix notes on the database layer - you can use e.g. [https://sqlitebrowser.org/](https://sqlitebrowser.org/) to open `document.db` file, find problematic notes and manually fix them. Don't forget to commit / write changes after you're done. + +How to reset the document +------------------------- + +If you previously just experimented with Trilium and want to get it to the initial state, you can do that by deleting the `document.db*` files, e.g. like this: + +```text-plain +rm document.db* +``` + +If you don't need to preserve e.g. the `config.ini`, then you can also delete the whole [data directory](data-directory.md) like this: + +```text-plain +rm -r ./trilium-data +``` + +After starting next time, Trilium will create a new initial document. diff --git a/Wiki/error-logs.md b/Wiki/error-logs.md new file mode 100644 index 0000000..8a553e2 --- /dev/null +++ b/Wiki/error-logs.md @@ -0,0 +1,42 @@ +# Error-logs +It's important to provide all available error logs together with bug reports. This page will show you how to do it. + +Backend logs +------------ + +Open [data directory](data-directory.md), go to `log` subdirectory and find the latest log file, e.g. `trilium-2022-12-14.log`. You can attach the whole file to the bug report (preferable) or open it and copy-paste only the last lines / lines you believe are relevant. + +If you have trouble finding it the log files, there's also an in-app option in top-left menu button -> Advanced -> Show backend log. + +Frontend logs +------------- + +To provide frontend logs, we need to open the Developer Console. Often the easiest way is to press `CTRL-SHIFT-I` which should work in most browsers (and desktop app). Make sure that the error producing action happened right before you copy&paste the errors, the console is cleared on app restart. + +If that doesn't work, then: + +* in Trilium desktop app, go to top-left menu button -> Advanced -> Open Dev Tools +* In Firefox/Chrome right-click anywhere in the page and click Inspect: + +![](images/error-logs-firefox-context-men.png) + +Once you have Dev Tools open, click on "Console" tab: + +![](images/error-logs-dev-tools.png) + +Copy-paste (or screenshot) the logs. It's better to provide not just errors, but the whole log, which might provide context while analyzing the bug. + +Providing sensitive data +------------------------ + +If you don't feel comfortable attaching the logs or anything sensitive to the public GitHub issues, feel free to mail them to [zadam.apps@gmail.com](#root/N3Zt66yETj9g) + +Use this email to also provide anything which could assist in analysing the bug - e.g. files/images/ZIPs being imported or [anonymized database](anonymized-database.md). + +### Exporting note subtree for reproduction + +Often times, bugs manifest themselves in specific notes and having them would greatly ease reproduction and fixing. + +In such case, please export the relevant note subtree by right-clicking it on the left tree, choosing Export - HTML as ZIP: + +![](images/error-logs-export-subtree.png) diff --git a/Wiki/etapi.md b/Wiki/etapi.md new file mode 100644 index 0000000..17b3851 --- /dev/null +++ b/Wiki/etapi.md @@ -0,0 +1,29 @@ +# ETAPI +ETAPI is Trilium's public/external REST API. It is available since Trilium v0.50. + +The documentation is in OpenAPI format, available [here](https://github.com/TriliumNext/Notes/blob/master/src/etapi/etapi.openapi.yaml). + +[trilium-py](https://github.com/Nriver/trilium-py) is a third-party Python implementation for ETAPI client, you can use Python to communicate with Trilium. + +Authentication +-------------- + +All operations have to be authenticated using a token. You can get this token either from Options -> ETAPI or programmatically using the `/auth/login` REST call (see the [spec](https://github.com/TriliumNext/Notes/blob/master/src/etapi/etapi.openapi.yaml)): + +```text-plain +GET https://myserver.com/etapi/app-info +Authorization: ETAPITOKEN +``` + +Alternatively, since 0.56 you can also use basic auth format: + +```text-plain +GET https://myserver.com/etapi/app-info +Authorization: Basic BATOKEN +``` + +* Where `BATOKEN = BASE64(username + ':' + password)` - this is a standard Basic Auth serialization +* Where `username` is "etapi" +* And `password` is the generated ETAPI token described above. + +Basic Auth is meant to be used with tools which support only basic auth. diff --git a/Wiki/events.md b/Wiki/events.md new file mode 100644 index 0000000..d081507 --- /dev/null +++ b/Wiki/events.md @@ -0,0 +1,31 @@ +# Events +[Script](scripts.md) notes can be triggered by events. Note that these are backend events and thus relation need to point to the "JS backend" code note. + +Global events +------------- + +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. + +* `run` + * `frontendStartup` - executes on frontend upon startup + * `mobileStartup` - executes on mobile frontend upon startup + * `backendStartup` - executes on backend upon startup + * `hourly` - executes once an hour on backend + * `daily` - executes once a day on backend + +Entity events +------------- + +Other events are bound to some entity, these are defined as [relations](attributes.md) - meaning that script is triggered only if note has this script attached to it through relations (or it can inherit it). + +* `runOnNoteCreation` - executes when note is created on backend +* `runOnNoteTitleChange` - executes when note title is changed (includes note creation as well) +* `runOnNoteContentChange` - executes when note content is changed (includes note creation as well). +* `runOnNoteChange` - executes when note is changed (includes note creation as well) +* `runOnNoteDeletion` - executes when note is being 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. +* `runOnBranchChange` (since v0.62) - executes when a branch is changed - either expanded status or prefix are changed. +* `runOnBranchDeletion` - executes when a branch is delete. Branch is a link between parent note and child note and is deleted e.g. when moving note (old branch/link is deleted). +* `runOnChildNoteCreation` - executes when new note is created under _this_ note +* `runOnAttributeCreation` - executes when new attribute is created under _this_ note +* `runOnAttributeChange` - executes when attribute is changed under _this_ note diff --git a/Wiki/evernote-import.md b/Wiki/evernote-import.md new file mode 100644 index 0000000..18ac730 --- /dev/null +++ b/Wiki/evernote-import.md @@ -0,0 +1,21 @@ +# Evernote-import +Trilium can import ENEX files which are used by Evernote for backup/export. One ENEX file represents content (notes and resources) of one notebook. + +Export ENEX from Evernote +------------------------- + +To export ENEX file, you need to have a _legacy_ desktop version of Evernote (i.e. not web/mobile). Right click on notebook and select export and follow the wizard. + +Import ENEX in Trilium +---------------------- + +Once you have ENEX file, you can import it to Trilium. Right click on some note (to which you want to import the file), click on "Import" and select the ENEX file. + +After importing the ENEX file, go over the imported notes and resources to be sure the import went well, and you didn't lose any data. + +Limitations +----------- + +All resources (except for images) are created as note's attachments. + +HTML inside ENEX files is not exactly valid so some formatting maybe broken or lost. You can report major problems into [Trilium issue tracker](https://github.com/TriliumNext/Notes/issues). %%{WARNING}%% diff --git a/Wiki/faq.md b/Wiki/faq.md new file mode 100644 index 0000000..a4e5076 --- /dev/null +++ b/Wiki/faq.md @@ -0,0 +1,65 @@ +# FAQ +Mac OS support +-------------- + +Originally, desktop builds of Trilium Notes has been available for Windows & Linux, but there has been a considerable demand for macOS build. + +So I made one, but I underestimated the differences and specifics of Mac platform which seems to require special handling in several places. My lack of knowledge and frankly willingness to learn & code Mac specific functionality resulted in a current state where [Trilium does not integrate well into the OS](https://github.com/TriliumNext/Notes/issues/511) %%{WARNING}%%. + +macOS build is from now on considered "unsupported". I will strive to keep it fundamentally functional, but I won't work on Mac specific features or integrations. Note that this is more of an acknowledgment of an existing state rather than sudden change of direction. + +Of course, PRs are welcome. + +Translation / localization support +---------------------------------- + +Trilium is currently available only in English. Translation to other languages is not planned in the near/medium term because it brings a significant maintenance overhead. This decision might be revisited once Trilium stabilizes into a more mature product. + +For Chinese, there's an unofficial fork [here](https://github.com/Nriver/trilium-translation). Use at your own risk. + +Multi user support +------------------ + +Common request is to allow multiple users collaborate, share notes etc. So far I'm resisting this because of these reasons: + +* it's a huge feature, or rather a Pandora's box of collaboration features like user management, permissions, conflict resolution, real-time editing of a note by multiple people etc. This would be a huge amount of work. Trilium Notes is project made mostly by one person in free time and that's unlikely to change in the future. +* given its size it would probably pivot the attention away from my main focus which is a personal note-taking +* the assumption that only single person has access to the app simplifies many things, or just outright makes them possible. In multi-user app, our [scripting](scripts.md) support would be a XSS security hole, while with the single user assumption it's an endless customizable tool. + +How to open multiple documents in one Trilium instance +------------------------------------------------------ + +This is normally not supported - one Trilium process can open only a single instance of a [document](document.md). However, you can run two Trilium processes (from one installation), each connected to a separate document. To achieve this, you need to set a location for the [data directory](data-directory.md) in the `TRILIUM_DATA_DIR` environment variable and separate port on `TRILIUM_PORT` environment variable. How to do that depends on the platform, in Unix-based systems you can achieve that by running command such as this: + +```text-plain +TRILIUM_DATA_DIR=/home/me/path/to/data/dir TRILIUM_PORT=12345 trilium +``` + +You can save this command into a `.sh` script file or make an alias. Do this similarly for a second instance with different data directory and port. + +Can I use Dropbox / Google Drive / OneDrive to sync data across multiple computers. +----------------------------------------------------------------------------------- + +No. + +These general purpose sync apps are not suitable to sync database files which are open and being worked on by another application. The result is that they will corrupt the database file, resulting in data loss and this message in the Trilium logs: + +> SqliteError: database disk image is malformed + +The only supported way to sync Trilium's data across the network is to use a [sync/web server](synchronization.md). + +Why database instead of flat files? +----------------------------------- + +Trilium stores notes in a [document](document.md) which is an SQLite database. People often ask why doesn't Trilium rather use flat files for note storage - it's fair question since flat files are easily interoperable, work with SCM/git etc. + +Short answer is that file systems are simply not powerful enough for what we want to achieve with Trilium. Using filesystem would mean fewer features with probably more problems. + +More detailed answer: + +* [clones](cloning-notes.md) are what you might call "hard directory link" in filesystem lingo, but this concept is not implemented in any filesystem +* filesystems make a distinction between directory and file while there's intentionally no such difference in Trilium +* files are stored in no particular order and user can't change this +* Trilium allows storing note [attributes](attributes.md) which could be represented in extended user attributes but their support differs greatly among different filesystems / operating systems +* Trilium makes links / relations between different notes which can be quickly retrieved / navigated (e.g. for [note map](note-map.md)). There's no such support in file systems which means these would have to be stored in some kind of side-car files (mini-databases). +* Filesystems are generally not transactional. While this is not completely required for a note-taking application, having transactions make it way easier to keep notes and their metadata in predictable and consistent state. diff --git a/Wiki/frontend-basics.md b/Wiki/frontend-basics.md new file mode 100644 index 0000000..dcd83ca --- /dev/null +++ b/Wiki/frontend-basics.md @@ -0,0 +1,60 @@ +# Frontend-Basics +Frontend API +------------ + +The frontend api supports two styles, regular scripts that are run with the current app and note context, and widgets that export an object to Trilium to be used in the UI. In both cases, the frontend api of Trilium is available to scripts running in the frontend context as global variable `api`. The members and methods of the api can be seen on the [Script API](script-api.md) page. + +Scripts +------- + +Scripts don't have any special requirements. They can be run at will using the execute button in the UI or they can be configured to run at certain times using [Attributes](attributes.md) on the note containing the script. + +### Global Events + +This attribute is called `#run` and it can have any of the following values: + +* `frontendStartup` - executes on frontend upon startup. +* `mobileStartup` - executes on mobile frontend upon startup. +* `backendStartup` - executes on backend upon startup. +* `hourly` - executes once an hour on backend. +* `daily` - executes once a day on backend. + +### Entity Events + +These events are triggered by certain [relations](attributes.md) to other notes. Meaning that the script is triggered only if the note has this script attached to it through relations (or it can inherit it). + +* `runOnNoteCreation` - executes when note is created on backend. +* `runOnNoteTitleChange` - executes when note title is changed (includes note creation as well). +* `runOnNoteContentChange` - executes when note content is changed (includes note creation as well). +* `runOnNoteChange` - executes when note is changed (includes note creation as well). +* `runOnNoteDeletion` - executes when note is being 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. +* `runOnBranchDeletion` - executes when a branch is delete. Branch is a link between parent note and child note and is deleted e.g. when moving note (old branch/link is deleted). +* `runOnChildNoteCreation` - executes when new note is created under this note. +* `runOnAttributeCreation` - executes when new attribute is created under this note. +* `runOnAttributeChange` - executes when attribute is changed under this note. + +Widgets +------- + +Conversely to scripts, widgets do have some specific requirements in order to work. A widget must: + +* Extend [BasicWidget](https://zadam.github.io/trilium/frontend_api/BasicWidget.html) or one of it's subclasses. +* Create a new instance and assign it to `module.exports`. +* Define a `parentWidget` member to determine where it should be displayed. +* Define a `position` (integer) that determines the location via sort order. +* Have a `#widget` attribute on the containing note. +* Create, render, and return your element in the render function. + * For [BasicWidget](https://zadam.github.io/trilium/frontend_api/BasicWidget.html) and [NoteContextAwareWidget](https://zadam.github.io/trilium/frontend_api/NoteContextAwareWidget.html) you should create `this.$widget` and render it in `doRender()`. + * For [RightPanelWidget](https://zadam.github.io/trilium/frontend_api/RightPanelWidget.html) the `this.$widget` and `doRender()` are already handled and you should instead return the value in `doRenderBody()`. + +### parentWidget + +* `left-pane` - This renders the widget on the left side of the screen where the note tree lives. +* `center-pane` - This renders the widget in the center of the layout in the same location that notes and splits appear. +* `note-detail-pane` - This renders the widget _with_ the note in the center pane. This means it can appear multiple times with splits. +* `right-pane` - This renders the widget to the right of any opened notes. + +### Tutorial + +For more information on building widgets, take a look at [Widget Basics](widget-basics.md). diff --git a/Wiki/home.md b/Wiki/home.md new file mode 100644 index 0000000..f332e8e --- /dev/null +++ b/Wiki/home.md @@ -0,0 +1,46 @@ +# Home +Overview +-------- + +Basic overview of the Trilium project is available at project homepage - [https://github.com/zadam/trilium#trilium-notes](https://github.com/zadam/trilium#trilium-notes) + +Inspiration for the name "Trilium": + +> Naming software is hard. I lived in Ontario when I first started the project and Trillium (the flower) is sort of a provincial logo, many institutions in Ontario are named "Trillium \[something\]". So I kept hearing/reading it almost everyday, I liked the sound of it and its nature motif, so I just reused it. + +> ~ Zadam (Trilium Developer) + +Documentation +------------- + +This [wiki](https://github.com/TriliumNext/Notes/wiki) %%{WARNING}%% contains additional and more in-depth information on some topics. See the sidebar for listing of all available pages. + +Quick Start +----------- + +Choose the setup +---------------- + +**Local only desktop/laptop** - Allows a single instance on a desktop and will save the notes locally on that desktop. + +1. [Desktop installation](desktop-installation.md) + +**Server with web only access** - Installs the application on the server and allows access from any web browser on any device, including mobile. + +1. [Server installation](server-installation.md) +2. [Mobile frontend](mobile-frontend.md) (optional) +3. [![Deploy](images/Home%20button.svg)](https://heroku.com/deploy?template=https://github.com/feilongfl/trilium-heroku) +4. [3rd party paid service to host a Trilium instance for you](https://trilium.cc/paid-hosting) + +**Combination of server and desktop/laptop** - Install the application on both a server, for web access and data synchronization, and desktop instance(s). This allows all the data to be stored on the server and either accessed from the web browser, or the desktop application. The desktop application will sync and store the data locally so that it can be used when offline. + +1. [Server installation](server-installation.md) +2. [Mobile frontend](mobile-frontend.md) (optional) +3. [Desktop installation](desktop-installation.md) +4. [Synchronization](synchronization.md) + +Basic concepts +-------------- + +1. Understand [Note](note.md) +2. Watch the [Screenshot tour](screenshot-tour.md) diff --git a/Wiki/images.md b/Wiki/images.md new file mode 100644 index 0000000..fbcd066 --- /dev/null +++ b/Wiki/images.md @@ -0,0 +1,24 @@ +# Images +Trilium supports storing and displaying images. Supported formats are JPEG, PNG and GIF. + +An image can be uploaded in the form of note's [attachment](attachments.md) or as a standalone [note](tree-concepts.md) placed into the [note tree](tree-concepts.md). Its reference can be copied into a text note, in order to display it in the text itself. + +Uploading images +---------------- + +To add an image to the note, simply drag it from file explorer onto the note editor inside Trilium and the image will be uploaded. + +![](images/upload-image.gif) + +Alternatively you can click on block toolbar and then on "Insert image": + +![](images/block-toolbar-insert-image.png) + +You can also copy and paste an image from web - the image will be (asynchronously) downloaded and embedded. + +Compression +----------- + +Since Trilium isn't really meant to be primary storage for image data, it attempts to compress and resize (with pretty aggressive settings) uploaded images before storing them to the database. You may then notice some quality degradation. Basic quality settings is available in Options -> Other. + +If you want to save images in their original resolution, it is recommended to save them as attachment to note (top-right "Note actions -> Import files"). diff --git a/Wiki/images/1-theme-gallery-image.png b/Wiki/images/1-theme-gallery-image.png new file mode 100644 index 0000000..7f07aeb Binary files /dev/null and b/Wiki/images/1-theme-gallery-image.png differ diff --git a/Wiki/images/1-workspace-image.png b/Wiki/images/1-workspace-image.png new file mode 100644 index 0000000..11f96f9 Binary files /dev/null and b/Wiki/images/1-workspace-image.png differ diff --git a/Wiki/images/2-theme-gallery-image.png b/Wiki/images/2-theme-gallery-image.png new file mode 100644 index 0000000..38ff826 Binary files /dev/null and b/Wiki/images/2-theme-gallery-image.png differ diff --git a/Wiki/images/canvas-note-image.png b/Wiki/images/canvas-note-image.png new file mode 100644 index 0000000..4ad24ad Binary files /dev/null and b/Wiki/images/canvas-note-image.png differ diff --git a/Wiki/images/custom-widget-image.png b/Wiki/images/custom-widget-image.png new file mode 100644 index 0000000..768dbdb Binary files /dev/null and b/Wiki/images/custom-widget-image.png differ diff --git a/Wiki/images/day-notes-image.png b/Wiki/images/day-notes-image.png new file mode 100644 index 0000000..131cc8e Binary files /dev/null and b/Wiki/images/day-notes-image.png differ diff --git a/Wiki/images/home-button.svg b/Wiki/images/home-button.svg new file mode 100644 index 0000000..8f579f8 --- /dev/null +++ b/Wiki/images/home-button.svg @@ -0,0 +1,18 @@ + + + + button + Created with Sketch. + + + + + + + + + + + + + \ No newline at end of file diff --git a/Wiki/images/saved-search-image.gif b/Wiki/images/saved-search-image.gif new file mode 100644 index 0000000..6f9433b Binary files /dev/null and b/Wiki/images/saved-search-image.gif differ diff --git a/Wiki/images/text-notes-image.png b/Wiki/images/text-notes-image.png new file mode 100644 index 0000000..d88b6da Binary files /dev/null and b/Wiki/images/text-notes-image.png differ diff --git a/Wiki/images/theme-gallery-bear-dark.png b/Wiki/images/theme-gallery-bear-dark.png new file mode 100644 index 0000000..d9bb4c9 Binary files /dev/null and b/Wiki/images/theme-gallery-bear-dark.png differ diff --git a/Wiki/images/theme-gallery-bear-white.png b/Wiki/images/theme-gallery-bear-white.png new file mode 100644 index 0000000..ea8a9a9 Binary files /dev/null and b/Wiki/images/theme-gallery-bear-white.png differ diff --git a/Wiki/images/theme-gallery-image.jpg b/Wiki/images/theme-gallery-image.jpg new file mode 100644 index 0000000..5b2eb96 Binary files /dev/null and b/Wiki/images/theme-gallery-image.jpg differ diff --git a/Wiki/images/theme-gallery-image.png b/Wiki/images/theme-gallery-image.png new file mode 100644 index 0000000..dda33ba Binary files /dev/null and b/Wiki/images/theme-gallery-image.png differ diff --git a/Wiki/images/theme-gallery-midnight.png b/Wiki/images/theme-gallery-midnight.png new file mode 100644 index 0000000..cd17cbf Binary files /dev/null and b/Wiki/images/theme-gallery-midnight.png differ diff --git a/Wiki/images/theme-gallery-neon-dark-demo-v.jpeg b/Wiki/images/theme-gallery-neon-dark-demo-v.jpeg new file mode 100644 index 0000000..71eaf4a Binary files /dev/null and b/Wiki/images/theme-gallery-neon-dark-demo-v.jpeg differ diff --git a/Wiki/images/theme-gallery-preview.jpg b/Wiki/images/theme-gallery-preview.jpg new file mode 100644 index 0000000..9e85e46 Binary files /dev/null and b/Wiki/images/theme-gallery-preview.jpg differ diff --git a/Wiki/images/theme-gallery-screenshot.png b/Wiki/images/theme-gallery-screenshot.png new file mode 100644 index 0000000..66b474e Binary files /dev/null and b/Wiki/images/theme-gallery-screenshot.png differ diff --git a/Wiki/images/theme-gallery-screenshot1.png b/Wiki/images/theme-gallery-screenshot1.png new file mode 100644 index 0000000..e3728d8 --- /dev/null +++ b/Wiki/images/theme-gallery-screenshot1.png @@ -0,0 +1,2204 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + trilium-theme-blue/img/screenshot1.png at main · SiriusXT/trilium-theme-blue · GitHub + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
+ Skip to content + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + + + + + +
+ + + + + + + + + +
+
+
+ + + + + + + + + +
+ +
+ +
+ +
+ + + + / + + trilium-theme-blue + + + Public +
+ + +
+ +
+ + +
+
+ +
+
+ + + + +
+ + + + + + +
+ + + + + + + + + + + + + + + + +

Latest commit

 

History

History
764 KB

screenshot1.png

File metadata and controls

764 KB
screenshot1.png
+ + + + + +
+ + + +
+
+ +
+ +
+

Footer

+ + + + +
+
+ + + + + © 2024 GitHub, Inc. + +
+ + +
+
+ + + + + + + + + + + + + + + + + + + +
+ +
+
+ + + diff --git a/Wiki/images/theme-gallery-screenshot2.png b/Wiki/images/theme-gallery-screenshot2.png new file mode 100644 index 0000000..ca3ae6c --- /dev/null +++ b/Wiki/images/theme-gallery-screenshot2.png @@ -0,0 +1,1720 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + trilium-theme-blue/img/screenshot2.png at main · SiriusXT/trilium-theme-blue · GitHub + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
+ Skip to content + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + + + + + +
+ + + + + + + + + +
+
+
+ + + + + + + + + +
+ +
+ +
+ +
+ + + + / + + trilium-theme-blue + + + Public +
+ + +
+ +
+ + +
+
+ +
+
+ + + + +
+ + + + + + +
+ + + + + + + + + + + + + + + + +
+ + + + + +
+ + + +
+
+ +
+ +
+

Footer

+ + + + +
+
+ + + + + © 2024 GitHub, Inc. + +
+ + +
+
+ + + + + + + + + + + + + + + + + + + +
+ +
+
+ + + diff --git a/Wiki/images/theme-gallery-scrn4-01.png b/Wiki/images/theme-gallery-scrn4-01.png new file mode 100644 index 0000000..23d565a Binary files /dev/null and b/Wiki/images/theme-gallery-scrn4-01.png differ diff --git a/Wiki/images/theme-gallery-trilium-theme-co.png b/Wiki/images/theme-gallery-trilium-theme-co.png new file mode 100644 index 0000000..55445fd Binary files /dev/null and b/Wiki/images/theme-gallery-trilium-theme-co.png differ diff --git a/Wiki/images/web-clipper-chrome-trilium-web.png b/Wiki/images/web-clipper-chrome-trilium-web.png new file mode 100644 index 0000000..f1ac0e4 Binary files /dev/null and b/Wiki/images/web-clipper-chrome-trilium-web.png differ diff --git a/Wiki/images/workspace-image.png b/Wiki/images/workspace-image.png new file mode 100644 index 0000000..4aa52be Binary files /dev/null and b/Wiki/images/workspace-image.png differ diff --git a/Wiki/import-docs.md b/Wiki/import-docs.md new file mode 100644 index 0000000..1185a7c --- /dev/null +++ b/Wiki/import-docs.md @@ -0,0 +1,17 @@ +# Importing Documentation + +To import these docs into your own Trilium instance: + +1. Download archive from main branch of this repo: +https://github.com/TriliumNext/Docs/archive/refs/heads/main.zip +2. In Trilim create a new note to act as branch for the docs +3. Right-click on the note, select "Import into note" and select downloaded `Docs-main.zip` file. + - Optionally uncheck "Shrink images" + +## Optional cleanup +- delete `!!!meta.json` +- Move `images` node down to the bottom (instead of dragging, it's easier to move out to parent node than back into Wiki. It will go to end of list automatically). + +For new releases delete the old docs note tree and start fresh, or you'll get duplicates. + +[0]: https://github.com/zadam/trilium/wiki diff --git a/Wiki/keyboard-shortcuts.md b/Wiki/keyboard-shortcuts.md new file mode 100644 index 0000000..0e9117f --- /dev/null +++ b/Wiki/keyboard-shortcuts.md @@ -0,0 +1,83 @@ +# Keyboard-shortcuts +This is supposed to be a complete list of keyboard shortcuts. Note that some of these may work only in certain contexts (e.g. in tree pane or note editor). + +It is also possible to configure most keyboard shortcuts in Options -> Keyboard shortcuts. Using `global:` prefix, you can assign a shortcut which will work even without Trilium being in focus (requires app restart to take effect). + +Note navigation +--------------- + +* `UP`, `DOWN` - go up/down in the list of notes, `CTRL-SHIFT-UP` and `CTRL-SHIFT-DOWN` work also from editor +* `LEFT`, `RIGHT` - collapse/expand node +* `ALT+LEFT`, `ALT+RIGHT` - go back / forwards in the history +* `CTRL+J` - show ["Jump to" dialog](note-navigation.md) +* `CTRL+.` - scroll to current note (useful when you scroll away from your note or your focus is currently in the editor) +* `BACKSPACE` - jumps to parent note +* `ALT+C` - collapse whole note tree +* `ALT+-` (alt with minus sign) - collapse subtree (if some subtree takes too much space on tree pane you can collapse it) +* you can define a [label](attributes.md) `#keyboardShortcut` with e.g. value `Ctrl+I`. Pressing this keyboard combination will then bring you to the note on which it is defined. Note that Trilium must be reloaded/restarted (Ctrl+R) for changes to be in effect. + +See demo of some of these features in [note navigation](note-navigation.md). + +Tabs +---- + +* `CTRL+click` - (or middle mouse click) on note link opens note in a new tab + +Only in desktop (electron build): + +* `CTRL+T` - opens empty tab +* `CTRL+W` - closes active tab +* `CTRL+Tab` - activates next tab +* `CTRL+Shift+Tab` - activates previous tab + +Creating notes +-------------- + +* `CTRL+O` - creates new note after the current note +* `CTRL+P` - creates new sub-note into current note +* `F2` - edit [prefix](note-navigation.md) of current note clone + +Moving / cloning notes +---------------------- + +* `CTRL+UP`, `CTRL+DOWN` - move note up/down in the note list +* `CTRL+LEFT` - move note up in the note tree +* `CTRL+RIGHT` - move note down in the note tree +* `SHIFT+UP`, `SHIFT+DOWN` - multi-select note above/below +* `CTRL+A` - select all notes in the current level +* `SHIFT+click` - multi select note which you clicked on +* `CTRL+C` - copies current note (or current selection) into clipboard (used for [cloning](cloning-notes.md) +* `CTRL+X` - cuts current (or current selection) note into clipboard (used for moving notes) +* `CTRL+V` - pastes note(s) as sub-note into current note (which is either move or clone depending on whether it was copied or cut into clipboard) +* `DEL` - delete note / sub-tree + +Editing notes +------------- + +Trilium uses CKEditor 5 for the [text notes](text-notes.md) and CodeMirror 5 for [code notes](code-notes.md). Check the documentation of these projects to see all their built-in keyboard shortcuts. + +* `ENTER` in tree pane switches from tree pane into note title. Enter from note title switches focus to text editor. `CTRL+.` switches back from editor to tree pane. +* `CTRL+K` - create / edit [external link](links.md) +* `CTRL+L` - create [internal (note) link](links.md) +* `ALT+T` - inserts current date and time at caret position +* `CTRL+.` - jump away from the editor to tree pane and scroll to current note + +Runtime shortcuts +----------------- + +These are hooked in Electron to be similar to native browser keyboard shortcuts. + +* `F5`, `CTRL-R` - reloads trilium frontend +* `CTRL+SHIFT+I` - show developer tools +* `CTRL+F` - show search dialog +* `CTRL+-` - zoom out +* `CTRL+=` - zoom in + +Other +----- + +* `ALT+O` - show SQL console (use only if you know what you're doing) +* `ALT+M` - distraction-free mode - display only note editor, everything else is hidden +* `F11` - toggle full screen +* `CTRL+S` - toggle [search](search.md) form in tree pane +* `ALT+A` - show note [attributes](attributes.md) dialog diff --git a/Wiki/kubernetes-server-installation.md b/Wiki/kubernetes-server-installation.md new file mode 100644 index 0000000..0e84485 --- /dev/null +++ b/Wiki/kubernetes-server-installation.md @@ -0,0 +1,31 @@ +# Kubernetes-server-installation +As Trilium can be run in Docker it also can be deployed in Kubernetes. Trilium can be applied to Kubernetes manually or per helm chart. + +The recommended way is helm. + +Root privileges +--------------- + +Trilium docker container needs to be run with root privileges. The node process inside the container will be started with reduced privileges (uid:gid 1000:1000) after some initialization logic. Make sure that you don't use a security context which changes the user id. To use a different uid:gid for file storage and the application, please use the USER\_UID & USER\_GID environment variables. + +The docker image will also fix the permissions of /home/node so you don't have to use an init container. + +Helm Install +------------ + +Unofficial helm chart by [ohdearaugustin](https://github.com/ohdearaugustin): [https://github.com/ohdearaugustin/charts](https://github.com/ohdearaugustin/charts) + +Add helm repository +------------------- + +```text-plain +helm repo add https://ohdearaugustin.github.io/charts/ +"" has been added to your repositories +``` + +How to install a chart +---------------------- + +Just `helm install /trilium-notes`. + +For more information on using Helm, refer to the Helm documentation. diff --git a/Wiki/link-map.md b/Wiki/link-map.md new file mode 100644 index 0000000..80fd944 --- /dev/null +++ b/Wiki/link-map.md @@ -0,0 +1,2 @@ +# Link-map +Map diff --git a/Wiki/links.md b/Wiki/links.md new file mode 100644 index 0000000..23d3854 --- /dev/null +++ b/Wiki/links.md @@ -0,0 +1,36 @@ +# Links +External links +-------------- + +External link is general web link targeting some external web resource - e.g. [https://en.wikipedia.org/wiki/South\_China\_Sea](https://en.wikipedia.org/wiki/South_China_Sea) is an external link to one Wikipedia page. + +External links are done through CKEditor native links. To create an external link, select text and press `CTRL-K` or wait for the "balloon" to appear and click link icon there. + +![](images/create-external-link.gif) + +You can follow external link by either double clicking (will open new tab/window) it or right clicking on them and choosing "Open in new tab". + +Internal links to notes +----------------------- + +Links to internal notes are created a bit differently. To create link to note at current cursor position, press `CTRL-L`. + +In the dialog you can see radio button to choose from different types of linking: + +* link title mirrors the note's current title - this is sometimes also called "reference link". Title of such links cannot be changed, instead it is always mirroring the title of linked note. This way the link title is never outdated +* link title can be changed arbitrarily - this is the traditional hyperlink - you link to a particular note and can choose the link title + +![](images/create-link-to-note.gif) + +You can follow the note link by double clicking it. + +Alternatively if you only wish to quickly preview the content, you can hover over the link and will see read only preview. + +### In-place linking + +Trilium also provides "inline" linking - type `@` and you'll see an autocomplete, just type few characters from the desired note title, press enter and you have a link. + +Note map +-------- + +Trilium provides a visualisation of incoming and outgoing links for a particular note. See [note map](note-map.md) for details. diff --git a/Wiki/manual-server-installation.md b/Wiki/manual-server-installation.md new file mode 100644 index 0000000..59541f2 --- /dev/null +++ b/Wiki/manual-server-installation.md @@ -0,0 +1,67 @@ +# Manual-server-installation +This page describes manually installing Trilium on your server. **Note that this is a not well supported way to install Trilium, problems may appear, information laid out here is quite out of date. It is recommended to use either Docker or packaged build installation.** + +Requirements +------------ + +Trilium is a node.js application. Supported (tested) version of node.js is latest 14.X.X and 16.X.X. Trilium might work with older versions as well. + +You can check your node version with this command (node.js needs to be installed): + +```text-plain +node --version +``` + +If your Linux distribution has only an outdated version of node.js, you can take a look at the installation instruction on node.js website, which covers most popular distributions. + +### Dependencies + +There are some dependencies required. You can see command for Debian and its derivatives (like Ubuntu) below: + +```text-plain +sudo apt install libpng16-16 libpng-dev pkg-config autoconf libtool build-essential nasm libx11-dev libxkbfile-dev +``` + +Installation +------------ + +### Download + +You can either download source code zip/tar from [https://github.com/TriliumNext/Notes/releases/latest\]\]](https://github.com/TriliumNext/Notes/releases/latest%5D%5D) %%{WARNING}%%or clone git repository **from stable branch** with + +```text-plain +git clone -b stable https://github.com/zadam/trilium.git %%{WARNING}%% +``` + +Installation +------------ + +```text-plain +cd trilium + +# download all node dependencies +npm install + +# make sure the better-sqlite3 binary is there +npm rebuild + +# bundles & minifies frontend JavaScript +npm run webpack +``` + +Run +--- + +```text-plain +cd trilium + +# using nohup to make sure trilium keeps running after user logs out +nohup TRILIUM_ENV=dev node src/www & +``` + +The application by default starts up on port 8080, so you can open your browser and navigate to [http://localhost:8080](http://localhost:8080) to access Trilium (replace "localhost" with your hostname). + +TLS +--- + +Don't forget to [configure TLS](tls-configuration.md) which is required for secure usage! diff --git a/Wiki/markdown.md b/Wiki/markdown.md new file mode 100644 index 0000000..78e6765 --- /dev/null +++ b/Wiki/markdown.md @@ -0,0 +1,43 @@ +# Markdown +Trilium Notes supports importing Markdown restricted to the [CommonMark specification](https://spec.commonmark.org/current/) (where [tables are not supported](https://github.com/TriliumNext/Notes/issues/2026) ) + +Import +------ + +### Clipboard import + +If you want to import just a chunk of markdown from clipboard, you can do it from editor block menu: + +![](images/markdown-inline-import.gif) + +### File import + +You can also import Markdown files from files: + +* single markdown file (with .md extension) +* whole tree of markdown files (packaged into [.zip](https://en.wikipedia.org/wiki/Tar_(computing)) archive) + * Markdown files need to be packaged into ZIP archive because browser can't read directories, only single files. + * You can use e.g. [7-zip](https://www.7-zip.org) to package directory of markdown files into the ZIP file + +\[\[gifs/markdown-file-import.gif\]\] + +![](images/markdown-file-import.gif) + +Export +------ + +### Subtree export + +You can export whole subtree to ZIP archive which will have directory structured modelled after subtree structure: + +![](images/markdown-export-subtree.gif) + +### Single note export + +If you want to export just single note without its subtree, you can do it from Note actions menu: + +![](images/markdown-export-note.gif) + +### Exporting protected notes + +If you want to export protected notes, enter a protected session first! This will export the notes in an unencrypted form, so if you reimport into Trilium, make sure to re-protect these notes. diff --git a/Wiki/mobile-frontend.md b/Wiki/mobile-frontend.md new file mode 100644 index 0000000..e49bac5 --- /dev/null +++ b/Wiki/mobile-frontend.md @@ -0,0 +1,38 @@ +# Mobile-frontend +Trilium ([server edition](server-installation.md)) has a mobile web frontend which is optimized for touch based devices - smartphones and tablets. It is activated automatically during login process based on browser detection. + +Mobile frontend is limited in features compared to full desktop frontend. See below for more details on this. + +Note that this is not an Android/iOS app, this is just mobile friendly web page served on the [server edition](server-installation.md). + +Screenshots +----------- + +### Mobile phone + +![](images/mobile-smartphone.png) + +### Tablet + +![](images/mobile-tablet.png) + +Limitations +----------- + +Mobile frontend provides only some of the features of the full desktop frontend: + +* it is possible to browse the whole note tree, read and edit all types of notes, but you can create only text notes +* reading and editing [protected notes](protected-notes.md) is possible, but creating them is not supported +* editing options is not supported +* cloning notes is not supported +* uploading file attachments is not supported + +Forcing mobile/desktop frontend +------------------------------- + +Trilium decides automatically whether to use mobile or desktop frontend. If this is not appropriate, you can use `?mobile` or `?desktop` query param on **login** page (Note: you might need to log out). + +Scripting +--------- + +You can alter the behavior with [scripts](scripts.md) just like for normal frontend. For script notes to be executed, they need to have labeled `#run=mobileStartup`. diff --git a/Wiki/nginx-proxy-setup.md b/Wiki/nginx-proxy-setup.md new file mode 100644 index 0000000..76459a7 --- /dev/null +++ b/Wiki/nginx-proxy-setup.md @@ -0,0 +1,52 @@ +# Nginx-proxy-setup +Configure Nginx proxy and HTTPS. The operating system here is Ubuntu 18.04. + +1. Download Nginx and remove Apache2 + +```text-plain +sudo apt-get install nginx +sudo apt-get remove apache2 +``` + +1. Create configure file + +```text-plain +cd /etc/nginx/conf.d +vim default.conf +``` + +1. Fill the file with the context shown below, part of the setting show be changed. Then you can enjoy your web with HTTPS forced and proxy. + +```text-plain +# This part is for proxy and HTTPS configure +server { + listen 443; + server_name trilium.example.net; #change trilium.example.net to your domain without HTTPS or HTTP. + ssl_certificate /etc/ssl/note/example.crt; #change /etc/ssl/note/example.crt to your path of crt file. + ssl_certificate_key /etc/ssl/note/example.net.key; #change /etc/ssl/note/example.net.key to your path of key file. + ssl on; + ssl_session_cache builtin:1000 shared:SSL:10m; + ssl_protocols TLSv1 TLSv1.1 TLSv1.2; + ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4; + ssl_prefer_server_ciphers on; + access_log /var/log/nginx/access.log; #check the path of access.log, if it doesn't fit your file, change it + + location / { + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_pass http://127.0.0.1:8080; # change it to a different port if non-default is used + proxy_read_timeout 90; + proxy_redirect http://127.0.0.1:8080 https://trilium.example.net; # change them based on your IP, port and domain + } +} +# This part is for HTTPS forced +server { + listen 80; + server_name trilium.example.net; # change to your domain + return 301 https://$server_name$request_uri; +} +``` diff --git a/Wiki/nixos-server-installation.md b/Wiki/nixos-server-installation.md new file mode 100644 index 0000000..7faf3b2 --- /dev/null +++ b/Wiki/nixos-server-installation.md @@ -0,0 +1,27 @@ +# NixOS-server-installation +This page describes configuring the Trilium module included in NixOS. + +Requirements +------------ + +[NixOS](https://nixos.org/) installation. + +Configuration +------------- + +Add this to your `configuration.nix`: + +```text-plain +services.trilium-server.enable = true; + +# default data directory: /var/lib/trilium +#services.trilium-server.dataDir = "/var/lib/trilium-sync-server"; + +# default bind address: 127.0.0.1, port 8080 +#services.trilium-server.host = "0.0.0.0"; +#services.trilium-server.port = 12783; +``` + +Uncomment any option you would like to change. + +See the [NixOS options list](https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=trilium-server) for more options (including nginx reverse proxy configuration). diff --git a/Wiki/note-hoisting.md b/Wiki/note-hoisting.md new file mode 100644 index 0000000..601cdbb --- /dev/null +++ b/Wiki/note-hoisting.md @@ -0,0 +1,8 @@ +# Note hoisting +Hoisting is a standard outliner feature which allows you to focus on (or "zoom into") a specific note and its subtree by hiding all parent and sibling notes. Demo: + +![](images/note-hoisting.gif) + +In addition to showing only this subtree, this also narrows both full text search and [“jump to note”](note-navigation.md) to just notes present in hoisted subtree. + +See also [Workspace](workspace.md) which extends this feature. diff --git a/Wiki/note-map.md b/Wiki/note-map.md new file mode 100644 index 0000000..e91f7c1 --- /dev/null +++ b/Wiki/note-map.md @@ -0,0 +1,28 @@ +# Note map +Note map is a visualization of connections between notes. + +This provides an insight into a structure ("web") of notes. + +There are two types of note map: + +Link Map +-------- + +Shows [relations](attributes.md) between notes: + +![](images/link-map.png) + +Tree Map +-------- + +Shows hierarchical map of notes: + +![](images/tree-map.png) + +See also +-------- + +[Relation map](relation-map.md) is a similar concept, with some differences: + +* note map is automatically generated while relation map must be created manually +* relation map is a type of note while a link map is just virtual visualization diff --git a/Wiki/note-navigation.md b/Wiki/note-navigation.md new file mode 100644 index 0000000..39c4ec1 --- /dev/null +++ b/Wiki/note-navigation.md @@ -0,0 +1,28 @@ +# Note navigation +One of the Trilium's goals is to provide fast and comfortable navigation between notes. + +Backwards and forward +--------------------- + +You can use alt-left and alt-right to move back and forward in history of viewed pages. + +This works identically to browser backwards / forwards, it's actually using built-in browser support for this. + +![](images/back-and-forwards.gif) + +Jump to note +------------ + +This is useful to quickly find and view arbitrary note - click on `Jump to` button on the top or press `CTRL-J`. Then type part of the note name and autocomplete will help you pick the desired note. + +![](images/jump-to.gif) + +### Recent notes + +Jump to note also has the ability to show the list of recently viewed / edited notes and quickly jump to it. + +To access this functionality, click on `Jump to` button on the top. By default, (when nothing is entered into autocomplete), this dialog will show the list of recent notes. + +Alternatively you can click on the "time" icon on the right. + +![](images/recent-notes.gif) diff --git a/Wiki/note-revisions.md b/Wiki/note-revisions.md new file mode 100644 index 0000000..654fa5b --- /dev/null +++ b/Wiki/note-revisions.md @@ -0,0 +1,10 @@ +# Note revisions +Trilium supports seamless versioning of notes by storing snapshots ("revisions") of notes at regular intervals. + +Time interval of taking note snapshot is configurable in the Options -> Other dialog. This provides a tradeoff between more revisions and more data to store. + +To turn off note versioning for a particular note (or subtree), add `disableVersioning` [label](attributes.md) to the note. + +Note revisions can be accessed through the button on the right of ribbon toolbar. + +![](images/note-revisions.png) diff --git a/Wiki/note.md b/Wiki/note.md new file mode 100644 index 0000000..cc2316e --- /dev/null +++ b/Wiki/note.md @@ -0,0 +1,44 @@ +# Note +Note is a central entity in Trilium. Main attributes of note are title and content. + +### Note types + +* [text note](text-notes.md) - this is default note type which allows you to put rich text, images etc. +* [code note](code-notes.md) - some kind of formal code, typically programming language (e.g. JavaScript) or data structure (e.g. JSON) +* [image note](https://github.com/TriliumNext/Notes/wiki/Images) - represents single image +* file note - represents uploaded file (e.g. docx MS Word document). +* render HTML note - this works as an output screen of attached [scripts](scripts.md) +* [saved search](saved-search.md) note - contains saved search query and dynamically displays result of the search as its sub-notes +* [relation map](relation-map.md) note - visualizes notes and their relations +* [book note](book-note.md) - displays its children notes, useful for reading many short notes +* mermaid - create diagrams and flowcharts using [mermaid.js ↗](https://github.com/mermaid-js/mermaid) +* [canvas note](canvas-note.md) - allows hand drawn notes and basic diagraming on an infinite canvas using [excalidraw ↗](https://github.com/excalidraw/excalidraw) + +In Trilium there's no specific "folder" note type. Any note can have children and thus be a folder. + +### Root note + +There's one special note called "root note" which is root of the note tree. All other notes are placed below it in the structure. + +### Tree structure + +Importantly, note itself doesn't carry information on its placement in note tree. See [cloning](cloning-notes.md) for details. + +Tree structure of notes can resemble file system - but compared to that notes in Trilium can act as both file and directory - meaning that note can both have its own content and have children. "Leaf note" is a note which doesn't have any children. + +### Deleting / undeleting notes + +When you delete a note in Trilium, it is actually only marked for deletion (soft-delete) - the actual content, title, attributes etc. are not deleted, only hidden. + +Within (by default) 7 days, it is possible to undelete these soft-deleted notes - open Recent Changes dialog, and you will see a list of all modified notes including the deleted ones. Notes available for undeletion have a link to do so. This is kind of "trash can" functionality known from e.g. Windows. + +Clicking an undelete will recover the note, it's content and attributes - note should be just as before being deleted. This action will also undelete note's children which have been deleted in the same action. + +To be able to undelete a note, it is necessary that deleted note's parent must be undeleted (otherwise there's no place where we can undelete it to). This might become a problem when you delete more notes in succession - the solution is then undelete in the reverse order of your deletion. + +After the 7 days (configurable) the notes will be "erased" - their title, content, revisions and attributes will be erased, and it will not be possible anymore to recover them (unless you restore [backup](backup.md)). + +See also +-------- + +* [Read-only note](read-only-note.md) diff --git a/Wiki/onenote.md b/Wiki/onenote.md new file mode 100644 index 0000000..70ef0ee --- /dev/null +++ b/Wiki/onenote.md @@ -0,0 +1,57 @@ +# Onenote +Migrating from OneNote (user contributed) +----------------------------------------- + +**This page describes a method to migrate via EverNote Legacy, but this app is no longer available/working.** + +Prep Onenote notes for best compatibility +----------------------------------------- + +* Remove Onenote Tags and replace with Emoji if possible (Onenote Tags will get imported into trilium as an image which clutters the Trilium tree somewhat) +* Make sure to use Onenote headings where applicable (These will be carried over correctly into Trilium) +* Remove extra whitespace in Onenote (Whitespace seems to be more noticible in Trilium, so removing it now will make it look nicer in trilium) +* If possible, try to avoid very long Onenote pages. Trilium works best with shorter concise pages with any number of sub or (sub-sub...) pages. +* Make sure numbered lists don't have unusual spaces between items in the list (Sometimes the numbered list will start at 1 again in Trilum if there is an extra space in the list in OneNote). + +Migration Procedure +------------------- + +### Import into Evernote from OneNote: + +* Install [Evernote Legacy](https://web.archive.org/web/20230327110646/https://help.evernote.com/hc/en-us/articles/360052560314). Current versions of Evernote do not have this functionality. (Requires Evernote account, but import works without internet connection - be sure to NOT sync notes to Evernote!). +* In evernote navigate to File > Import > Onenote > Notebook > Section > OK + +If exporting all sections at a time, they will not be grouped in folders - they will all be added to a single folder, but the order will be kept, so you can re-group into folders after importing to Trilium + +### Export from Evernote + +* Right click on the created notebook in Evernote and choose "Export Notes…" +* Use the default export format of .enex + +### Cleanup enex file (optional) + +* If the Onenote header (that is at the top of each Onenote page) is not desired, you can use the following regex to remove them in a text editor like VsCode: + + Find (using regex): `. { + const dateNote = await api.getDayNote(todayDateStr); + + ({note: logNote} = await api.createNote(dateNote.noteId, 'log')); +}, [todayDateStr]); + +api.activateNote(todayNote.noteId); +``` + +all the `await` (and `async`) should disappear from the backend code, but should remain when calling backend from frontend (that's still async): + +```text-plain +const todayDateStr = api.formatDateISO(new Date()); + +const todayNote = await api.runOnBackend(todayDateStr => { + const dateNote = api.getDayNote(todayDateStr); + + ({note: logNote} = api.createNote(dateNote.noteId, 'log')); +}, [todayDateStr]); + +api.activateNote(todayNote.noteId); +``` + +### Migrate custom themes + +With the redesign you might need to adjust your custom themes - check the modified list of available CSS variables in the [default theme](https://github.com/TriliumNext/Notes/blob/master/src/public/stylesheets/theme-light.css). If your theme also uses CSS selectors then that will probably have to be rewritten as well. + +Themes are annotated with `#appTheme` label, previously this label could but did not have to contain value - with this release the value is required so define the label as e.g. `#appTheme=my-theme-name`. + +Additionally, CSS themes are now loaded differently than before - previously all themes were loaded at the startup and which one was active was decided by the active CSS class. Themes were then prefixed like this: + +```text-plain +body.theme-steel-blue { + --main-font-family: 'Raleway' !important; + --main-font-size: normal; + + --tree-font-family: inherit; + --tree-font-size: normal; + ... +} + +body.theme-steel-blue .note-detail-editable-text, body.theme-steel-blue .note-detail-readonly-text { + font-size: 120%; +} +``` + +This prefixing is not needed anymore (and also doesn't work anymore). Remove the prefixes like this: + +```text-plain +:root { + --main-font-family: 'Raleway'; + --main-font-size: normal; + + --tree-font-family: 'Raleway'; + --tree-font-size: normal; + ... +} + +body .note-detail-editable-text, body .note-detail-readonly-text { + font-size: 120%; +} +``` diff --git a/Wiki/saved-search.md b/Wiki/saved-search.md new file mode 100644 index 0000000..a8e05d7 --- /dev/null +++ b/Wiki/saved-search.md @@ -0,0 +1,9 @@ +# Saved-search +Trilium provides a way to save common search as a note in the note tree. Search results will then appear as sub-notes of this "saved search" note. You can see how this works in action: + +![save-search](images/Saved-search%20image.gif) + +Location +-------- + +Saved search is by default stored in the day note. You can also mark some note with `#searchHome` label, all saved searches will be then saved there. There's also `#workspaceSearchHome` variant for \[\[workspaces|workspace\]\]. diff --git a/Wiki/screenshot-tour.md b/Wiki/screenshot-tour.md new file mode 100644 index 0000000..17440bb --- /dev/null +++ b/Wiki/screenshot-tour.md @@ -0,0 +1,46 @@ +# Screenshot tour +Sometimes the fastest way to assess the software is just through screenshots so here they are: + +![](images/screenshot.png) + +![](images/dark-theme.png) + +See [Themes](themes.md). + +![](images/code-note.png) + +This shows [code note](code-notes.md) editor. + +![](images/promoted-attributes-queen.png) + +See [promoted attributes](promoted-attributes.md) + +![](images/relation-map-family.png) + +See [relation map](relation-map.md). + +![](images/link-map.png) + +See [link map](link-map.md). + +![](images/day-notes.png) + +See [Day notes](day-notes.md). + +![](images/weight-tracker.png) + +See [Weight tracker](weight-tracker.md). + +![](images/task-manager.png) + +See [Task manager](task-manager.md). + +![](images/note-revisions.png) + +See [Note revisions](note-revisions.md). + +![](images/mobile-smartphone.png) + +![](images/mobile-tablet.png) + +See [Mobile frontend](mobile-frontend.md). diff --git a/Wiki/script-api.md b/Wiki/script-api.md new file mode 100644 index 0000000..0233f5b --- /dev/null +++ b/Wiki/script-api.md @@ -0,0 +1,10 @@ +# Script API +For [Scripts](scripts.md) to do anything useful, Trilium publishes "Script API". Actually there are two such APIs: + +* [Frontend API](https://zadam.github.io/trilium/frontend_api/FrontendScriptApi.html) %%{WARNING}%% +* [Backend API](https://zadam.github.io/trilium/backend_api/BackendScriptApi.html) %%{WARNING}%% + +Backwards compatibility +----------------------- + +Note that Script API is now experimental and subject to change in the future. diff --git a/Wiki/scripts.md b/Wiki/scripts.md new file mode 100644 index 0000000..39f75ba --- /dev/null +++ b/Wiki/scripts.md @@ -0,0 +1,58 @@ +# Scripts +Trilium supports creating [code notes](code-notes.md), i.e. notes which allow you to store some programming code and highlight it. Special case is JavaScript code notes which can also be executed inside Trilium which can in conjunction with [Script API](script-api.md) provide extra functionality. + +Scripting +--------- + +To go further I must explain basic architecture of Trilium - in its essence it is a classic web application - it has these two main components: + +* frontend running in the browser (using HTML, CSS, JavaScript) - this is mainly used to interact with the user, display notes etc. +* backend running JavaScript code in node.js runtime - this is responsible for e.g. storing notes, encrypting them etc. + +So we have frontend and backend, each with their own set of responsibilities, but their common feature is that they both run JavaScript code. Add to this the fact, that we're able to create JavaScript \[\[code notes\]\] and we're onto something. + +Button use case +--------------- + +Let's take a look at our demo script (shipped with default Trilium [document](document.md)) - Task manager. One of the things this script does is adding a button to the Trilium interface which will allow user to easily add new Task (TODO item). + +![](images/button-script.png) + +First take a look at the red circle all the way on the top - this what we want to achieve - new button in UI which will create new note representing a task/todo item. + +Red point below the first one marks the note type we have created for this script - it's "JavaScript frontend". It's frontend because adding button to UI is clearly frontend responsibility. + +In the note content you can see the code which calls one of the API methods, this one is specifically meant to add new buttons. Code needs to set few button properties: + +* button title +* icon which should appear on the button +* optional shortcut under which you can trigger the button +* most importantly "action" - what must happen when button is clicked + +### Action handler + +Saving the note to the database is backend's responsibility, so we immediately pass control to the backend and ask it to create a note. Once this is done, we show the newly created note so that the user can set the task title and maybe some attributes. + +### Script execution + +So we have a script which will add the button to the toolbar. But how can we execute it? One possibility is to click on "play" icon (marked by red circle). The problem with this is that this UI change is time bound by Trilium runtime so when we restart Trilium, button won't be there. + +We need to execute it every time Trilium starts up, but we probably don't want to have to manually click on play button on every start up. + +The solution is marked by red circle at the bottom - this note has [label](attributes.md) `#run=frontendStartup` - this is one of the "system" labels which Trilium understands. As you might guess, this will cause all such labeled script notes to be executed once Trilium frontend starts up. + +(`#run=frontendStartup` does not work for \[\[mobile server frontend|Mobile frontend\]\] - if you want to have scripts running there, give the script `#run=mobileStartup` label) + +### More showcases + +You can see more scripting with explanation in [Advanced showcases](advanced-showcases.md) + +Events +------ + +See [Events](events.md). + +Script API +---------- + +See [Script API](script-api.md). diff --git a/Wiki/search.md b/Wiki/search.md new file mode 100644 index 0000000..1a200e6 --- /dev/null +++ b/Wiki/search.md @@ -0,0 +1,192 @@ +# Search +* local search - searches within currently displayed note. Press `CTRL-F` to open the search dialog. In server version this is handled by the browser, in desktop (electron) version there's a separate dialog. +* note search - you can find notes by search for text in the title, note's content or note's [attributes](attributes.md). You can also [save search](saved-search.md). + * You can activate note search by clicking on magnifier icon on the left or pressing `CTRL-S` keyboard [shortcut](keyboard-shortcuts.md). + +Simple note search examples +--------------------------- + +`rings tolkien` - fulltext search, this will try to find notes which have anywhere words "rings" and "tolkien" + +`"The Lord of the Rings" Tolkien` - same as above, but "The Lord of the Rings" must be exact match + +`note.content *=* rings OR note.content *=* tolkien` to find notes which contain "rings" or "tolkien" + +`towers #book` - combination of fulltext search with attribute search - this looks for notes containing "towers" word anywhere, and they also need to have "book" label + +`towers #book or #author` - searches notes containing "towers" word anywhere and matching note must have either "book" or "author" label + +`towers #!book` - searches notes containing "towers" word anywhere and which do **not** have "book" label + +`#book #publicationYear = 1954` - will find notes with "book" label and label "publicationYear" containing this specific value + +`#genre *=* fan` - matches notes with "genre" label which has value which contains "fan" substring. Besides `*=*` for "contains", there's also `=*` for "starts with", `*=` for "ends with", `!=` for "is not equal to" + +`#book #publicationYear >= 1950 #publicationYear < 1960` - you can also use numeric operators - this will find all books published in the 1950s + +`#dateNote >= TODAY-30` - special "smart search" will find notes with label "dateNote" with date corresponding to last 30 days. Complete list of smart values: NOW +- seconds, TODAY +- days, MONTH +- months, YEAR +- years + +`~author.title *=* Tolkien` - find notes which have relation "author" which points to a note with title containing word "Tolkien" + +`#publicationYear %= '19[0-9]{2}'` - operator '%=' matches a regular expression (regex). Since Trilium 0.52 + +Advanced use cases +------------------ + +`~author.relations.son.title = 'Christopher Tolkien'` - This will search for notes which have “author” relation to a note which has a “son” relation to “Christopher Tolkien” note. This situation can be modeled by this note structure: + +* Books + * Lord of the Rings + * label: “book” + * relation: “author” points to “J. R. R. Tolkien” note +* People + * J. R. R. Tolkien + * relation “son” points to "Christopher Tolkien" note + * Christopher Tolkien + +`~author.title *= Tolkien OR (#publicationDate >= 1954 AND #publicationDate <= 1960)` - you can also use boolean expressions and parenthesis to group expressions + +However, if your search expression starts with a parenthesis, it needs to be prepended by an "expression separator sign", either # or ~. So the equivalent expression, just reordered, would look like: + +`# (#publicationDate >= 1954 AND #publicationDate <= 1960) OR ~author.title *= Tolkien` + +`note.parents.title = 'Books'` will find all notes which have (at least one) parent note with name “Book”. + +`note.parents.parents.title = 'Books'` This again works transitively, so this will find notes whose parent of parent is named ‘Book’. + +`note.ancestors.title = 'Books'` This is sort of extension of parents - this will find notes which have an ancestor anywhere in their note path (so parent, grandparent, grand-grand-parent …) with title ‘Book’. This is a nice way how to reduce the scope of the search to a particular subtree. + +`note.children.title = 'sub-note'` So this works in the other direction and will find notes which have (at least one) child called “sub-note”. + +### Search with note properties + +Note has certain properties which can be also used for searching: + +* `noteId` +* `dateModified` - local dates are in the format "2019-05-19 16:39:47.003+0200" +* `dateCreated` +* `utcDateModified` - UTC dates are in the format "2019-05-19 14:39:47.003Z" +* `utcDateCreated` +* `isProtected` (true, false) +* `type` (text, code, search, relation-map, book) +* `title` (when you want to search specifically the title) +* `text` - search through note title and content +* `content` - search just through note content +* `rawContent` - search through raw note content (HTML tags are kept). Since v0.46. +* `ownedLabelCount` +* `labelCount` (includes inherited labels) +* `ownedRelationCount` +* `relationCount` (includes inherited relations) +* `ownedRelationCountIncludingLinks` and `relationCountIncludingLinks` - count also includes auto-generated relations `imageLink`, `internalLink`, `relationMapLink` and `includeNoteLink` +* `ownedAttributeCount` = `ownedLabelCount` + `ownedRelationCount` +* `attributeCount` = `labelCount` + `relationCount` +* `targetRelationCount` - number of relations targeting this note +* `targetRelationCountIncludingLinks` - count also includes auto-generated relations `imageLink`, `internalLink`, `relationMapLink` and `includeNoteLink` +* `parentCount` - essentially number of [clones](cloning-notes.md) +* `childrenCount` +* `isArchived` (true, false) +* `contentSize` - size of note content in bytes. +* `noteSize` - estimated size of complete note (chiefly note content + note revision contents). Since v0.46. +* `revisionCount` - number of note revisions. + +These are accessed through `note.`, e.g.: + +```text-plain +note.type = code AND note.mime = 'application/json' +``` + +### Order by and limit + +```text-plain +#author=Tolkien orderBy #publicationDate desc, note.title limit 10 +``` + +The example above will do the following things (in this sequence): + +1. find notes with label author having value “Tolkien” +2. order the results by publicationDate in descending order (so the newest first) +3. in case publication date is equal, use note.title as secondary ordering in ascending order (`asc` is the default and thus can be omitted) +4. take only the first 10 results + +### Negation + +Some queries can be expressed only with negation: + +```text-plain +#book AND not(note.ancestor.title = 'Tolkien') +``` + +This will find all the book notes which are not in the "Tolkien" subtree. + +Under the hood +-------------- + +### Label and relation shortcuts + +"Full" syntax for searching by labels is the following: + +`note.labels.publicationYear = 1954` or `note.relations.author.title *=* Tolkien` + +But given that searching by labels and relations is pretty common, there exists also a shortcut syntax: + +`#publicationYear = 1954` or `#author.title *=* Tolkien` respectively. + +### Separating fulltext and attribute parts + +As you may have noticed from the examples above, search syntax allows seamlessly combining fulltext search with attribute-based search. How is this done? + +Take `tolkien #book` as an example. It contains: + +1. fulltext tokens - `tolkien` +2. attribute expressions - `#book` + +The tricky part is to find out where does the fulltext end and where the attribute expression begins. This is done by detecting certain stop-characters/words - all tokens are considered as fulltext before one of `#`, `~` or `note.` prefixes are encountered. After that, all characters/tokens are understood as attribute expression. + +If you want to use `#`, `~` or `note.` as part of fulltext, you need to escape them, see below for details. + +There are certain corner cases where this is not sufficient, e.g: + +```text-plain +tolkien (#publicationYear >= 1950 AND #publicationYear < 1960) OR #book` +``` + +Here the expression starts with `(` which isn't (intentionally) a stop-character, so the query above will not actually work as intended. Instead, in these corner cases we need to add a separate extra stop character - `#` or `~` so the fixed query should look like: + +```text-plain +tolkien # (#publicationYear >= 1950 AND #publicationYear < 1960) OR #book` +``` + +The extra stop character has no other effect other than separating the fulltext part from the attribute expression part. + +### Escaping special characters + +Symbols or values sometimes have special meaning, which might be not what you intend. This can be fixed by either enclosing the strings containing special characters into quotes or escaping individual characters with backslash: + +`"note.txt"` - "note." is normally stop-prefix, but here it will be used for fulltext search + +`\#hash` - `#` is normally stop-character, but here it's escaped with backslash, so it's again used for fulltext + +`#myLabel = 'Say "Hello World"'` + +There are three supported types of quotes - single, double and backtick. + +### Type coercion + +It's important to realize that a label value is always technically a string, even if it contains logically different value. This then allows you to do things like: + +```text-plain +note.dateCreated =* '2019-05' +``` + +This will find notes created in May 2019 by simply doing string "starts with" operation on the date. + +This approach does not work well with numbers though, so whenever there is a numeric operator detected, the label values will be coerced from their normal string form into a numeric value for comparison. This then allows for e.g. `#publicationYear >= 1960` work correctly. + +Auto trigger search from URL +---------------------------- + +Opening Trilium like in the example below will open the search pane and automatically trigger search for "abc": + +```text-plain +http://localhost:8080/#?searchString=abc +``` diff --git a/Wiki/server-installation.md b/Wiki/server-installation.md new file mode 100644 index 0000000..b65f4c6 --- /dev/null +++ b/Wiki/server-installation.md @@ -0,0 +1,66 @@ +# Server-installation +This pages describes installing Trilium on your own server. You might want to do this in case you want to set up [sync](synchronization.md) or you want to use it as online version of Trilium accessible from anywhere. The server installation is a fully functioning instance i.e. "web editor". + +There are several options how to do this, each one with some advantage: + +* Recommended: [Docker](docker-server-installation.md) - images for **AMD64** and **ARM** +* [Packaged server installation](packaged-server-installation.md) +* There's a [3rd party paid service to host a Trilium instance for you](https://trilium.cc/paid-hosting) +* [Manual installation](manual-server-installation.md) +* [Kubernetes](kubernetes-server-installation.md) +* [Cloudron](https://www.cloudron.io/store/com.github.trilium.cloudronapp.html) +* [HomelabOS](https://homelabos.com/docs/software/trilium/) +* [NixOS module](nixos-server-installation.md) + +Server installation has both web and [mobile frontend](mobile-frontend.md). + +Configuration +------------- + +For server installations, you might want to configure e.g. port or [TLS](tls-configuration.md). This is done in the Trilium config file, by default it's in `config.ini` in the [data directory](data-directory.md). You can start creating your configuration by copying the provided `config-sample.ini` with default values to `config.ini`. + +### Config location + +`config.ini`, [document](document.md) and some other important Trilium data files are by default persisted in the [data directory](data-directory.md)\]\]. + +If this is not desired, you may change it via `TRILIUM_DATA_DIR` environment variable to some other location, e.g.: + +```text-plain +export TRILIUM_DATA_DIR=/home/myuser/data/my-trilium-data +``` + +### Disable authentication + +Among others, you can also disable authentication (in case you run on localhost only or authentication is handled by another component) by adding the following to `config.ini`: + +```text-plain +[General] +noAuthentication=true +``` + +Reverse proxy setup +------------------- + +### nginx + +```text-plain +location /trilium/ { + proxy_pass http://127.0.0.1:8080/; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_cache_bypass $http_upgrade; +} +``` + +It's also advised to add following to `server {}` block to not limit size of payloads: + +```text-plain +# set to 0 for unlimited. Default is 1M. +client_max_body_size 0; +``` + +### Apache + +See [Apache proxy setup](apache-proxy-setup.md). diff --git a/Wiki/sharing.md b/Wiki/sharing.md new file mode 100644 index 0000000..884c5f9 --- /dev/null +++ b/Wiki/sharing.md @@ -0,0 +1,125 @@ +# Sharing +Trilium provides a feature to share selected notes as **publicly accessible** read only documents. + +The basic prerequisite for this feature is to have a [server installation](server-installation.md) - this is where the notes will be hosted from. + +Share note +---------- + +Click on the "shared" switch, URL appears on which you can click.![](images/share-single-note.png) + +And this is the opened link: + +![](images/share-single-note-web.png) + +The URL refers to the localhost (127.0.0.1) because there's no configured sync server. + +Share a note subtree +-------------------- + +Sharing a note actually shares a whole subtree of notes, the note shown above just didn't have any children. + +If I share the whole "Formatting" subtree then the page looks like this: + +![](images/share-multiple-notes-web.png) + +You can see a basic navigation on the right. With this you can create small websites. + +Showing list of all shared notes +-------------------------------- + +You can click on the "Show Shared Notes Subtree" to see the list of all shared notes + +Security +-------- + +The notes you share are published on the open internet and can be accessed by anybody. The fact that the URLs look randomly does not provide real security guarantees. Please don't put sensitive information into shared notes. + +There is an opt-in feature to require a username/password, see `#shareCredentials` below. + +Advanced options +---------------- + +### Styling the shared notes + +The default shared page is pretty rudimentary. In case you want to style it more nicely, you can: + +* add a `~shareCss` relation to a CSS code note which will be linked in the shared page + * in case you want this to apply to the whole subtree, don't forget to make the label inheritable + * the linked CSS code note needs to be also in the shared subtree. If you want to hide it from left tree navigation, add `#shareHiddenFromTree` label to the CSS code note. +* if you make extensive styling changes, then it's recommended to use `#shareOmitDefaultCss` on the shared subtree so that you don't need to override the default stylesheet (this will also avoid problems in the future when the default CSS changes). + +### Scripting + +It's possible to inject a JavaScript note to the shared note using `~shareJs` relation. + +In case you want to access e.g. attributes or traverse the tree in the linked JavaScript note, you can use the API available through global [`fetchNote(noteId = current)` function](https://github.com/TriliumNext/Notes/blob/master/src/public/app/share.js), e.g.: + +```text-plain +const currentNote = await fetchNote(); +const parentNote = await fetchNote(currentNote.parentNoteIds[0]); + +for (const attr of parentNote.attributes) { + console.log(attr.type, attr.name, attr.value); +} +``` + +### Creating human-readable URL aliases + +Shared notes are accessible using URLs like `http://domain/share/knvU8aJy4dJ7`, where the last part is the note's ID. + +You can add `#shareAlias` to individual notes to make the URLs nicer, e.g. `#shareAlias=highlighting` will make the URL look like `http://domain/share/highlighting`. + +Note that you are responsible for keeping the aliases unique. + +Using "subpaths", i. e. to declare an alias with `/` within, is not supported. + +### Seeing all shared notes + +All shared notes are grouped under automatically managed "Shared Notes" note. Besides seeing what's shared, you can also effectively share/unshare notes by cloning/moving them from/to this note. + +![](images/shared-list.png) + +### Favicon + +You can define a custom favicon used for shared pages by create a relation `~shareFavicon` pointing to the file note containing the favicon (in e.g. the `ico` format). + +### Sharing a note as the root + +You can add the `#shareRoot` attribute to a folder or note, and it will be linked when you visit [http://domain/share](http://domain/share). This can make it easier to use Trilium as a fully-fledged website because you can create a note to act as a "home-page". + +Consider also combining this with `#shareIndex` which will display the list of all shared notes. + +### Protecting shared notes with a password + +It is possible to optionally protect shared notes with credentials. + +To do that, create a label in the format `#shareCredentials="username:password"` to a note which you want to protect. Typically, you want to make the whole sub-tree protected like that, so don't forget to make this label inheritable. + +Keep in mind that the default state is public, so make sure everything you need to protect has this label (either owned or inherited). + +Note titles of password protected notes may appear in the links and navigation from unprotected notes. + +Password-protecting shared notes is available since 0.54. + +### Other options + +* if a note has `#shareRaw` label, the note will be shared raw, without HTML wrapper +* if a note has `#shareDisallowRobotIndexing` label, it will carry `` meta tag and `X-Robots-Tag: noindex` header, which will advise crawlers to skip this page +* if a text note has `#shareIndex` label, its content will display a list of all shared note roots (since v0.57) + +Limitations +----------- + +Shared notes functionality is compared to standard functionality very limited. + +The not exhaustive list of **what is missing** is: + +* relation map support +* book notes show only children note list +* code notes have no highlighting +* note tree is static +* Protected notes cannot be shared +* include notes + +Some of these limitations might be removed/mitigated in the future. diff --git a/Wiki/sorting.md b/Wiki/sorting.md new file mode 100644 index 0000000..7602942 --- /dev/null +++ b/Wiki/sorting.md @@ -0,0 +1,25 @@ +# Sorting +One time sorting +---------------- + +You can sort notes one time by right-clicking parent note in the note tree, Advanced -> Sort notes by ... + +Automatic / permanent sorting +----------------------------- + +Child notes can be kept sorted by attaching [labels](attributes.md) to the parent note: + +* `#sorted` - enables sorting, can optionally include name of the note's property/label (see details below) +* `#sortDirection` - by default ascending, set it to `desc` value to reverse the sort order +* `#sortFoldersFirst` - notes with children will be sorted on top + +Sorting works by comparing note property or a specific label on the child notes. + +There are 4 sorting levels, where the first one has the highest priority and the lower one will be applied only if the 2 compared notes are equal based on higher priority comparison. + +1. implicit sorting by `#top` label - child notes with this label will appear on the top of the folder. +2. implicit sorting by `#bottom` label (since Trilium 0.62) - child notes with this label will appear on the bottom of the folder. +3. sorting by child's property or a specific label defined on the parent note's `#sorted` label a) parent note has `#sorted` with no value - by default sorting will be done alphabetically b) parent note has `#sorted=title` or `#sorted=dateModified` or `#sorted=dateCreated` - sorting will be done based on the defined note's property c) parent note has `#sorted` label with any other value - this value is the name of the child note's label, whose value will be used for sorting. So e.g. you set `#sorted=myOrder` on the parent note and then child notes will have labels `#myOrder=001`, \`#myOrder=002" etc. +4. sorting of "last resort" is alphabetical + +All comparisons are made string-wise - e.g. "1" < "2" or "2020-10-10" < "2021-01-15" but also "2" > "10". diff --git a/Wiki/synchronization.md b/Wiki/synchronization.md new file mode 100644 index 0000000..bb9b680 --- /dev/null +++ b/Wiki/synchronization.md @@ -0,0 +1,85 @@ +# Synchronization +Trilium is offline-first note-taking application - when you use the desktop application, all the data is stored locally, but you also have an option to set up synchronization to the server instance. When you add another desktop client, you can get to star-shaped topology: + +![](images/star-topology.png) + +This means that there's one central server (we'll call this instance _sync server_) and several _client_ (sometimes called _desktop_) instances which all point to this sync server and synchronize against it. + +Once sync is set up, synchronization is automatic and ongoing - you don't need to trigger it manually. It should "just work". + +How to set up synchronization +----------------------------- + +### Security + +Please note that setting up server securely is not easy and far reaching mistakes can be made. It is especially important to use a valid TLS certificate (https) instead of unencrypted/unauthenticated HTTP. + +### Setup synchronization from desktop instance to sync server + +This approach is used when you already have a desktop instance of Trilium and you want to [setup sync server on your web host](server-installation.md). + +So let's assume your server instance is already deployed, but it's uninitialized (no data). Then open your desktop instance, click on Options -> Sync tab -> Sync configuration and set "Server instance address" to point to your sync server. Click Save. + +![](images/sync-config.png) + +Now click on "Test sync" button which will tell you if the handshake with sync server succeeded. If yes, sync with sync server started - client started pushing all the data towards the server instance. This might take some time to finish, but you can close the Options dialog and keep using Trilium. + +You can also check the server instance periodically to see if the sync finished. Once it's finished, you should see the login screen. + +### Setup synchronization from sync server to desktop instance + +This is used when you already have sync server, and you want to set up a desktop instance to sync with (from) it. + +Here we assume that you downloaded [the most recent release](https://github.com/TriliumNext/Notes/releases/latest) for your platform, unzipped it and ran it. + +Since the desktop instance is completely empty, it will first ask if you want to create an initial document, or you want to set up sync with sync server - you need to choose the second option. + +![](images/sync-init.png) + +You'll need to configure Trilium server address and importantly also correct username / password (sync setup requires authentication). + +Click on "Finish setup" button and if everything went fine, you'll see this screen: + +![](images/sync-in-progress.png) + +Once the sync is finished, you'll be automatically redirected to the Trilium application. + +Proxy setup +----------- + +Two different setups are supported: + +* you can explicitly set proxy server to be used in Options / Sync. Only unauthenticated proxy servers are currently supported. +* if no proxy server is explicitly configured, then Trilium will use system proxy settings + +Troubleshooting +--------------- + +### Different date/time on client and server + +For a successful sync, both client and server need to have save date time, with a tolerance of maximum 5 minutes difference. + +Certificate issues +------------------ + +When TLS is in use, Trilium client will attempt to verify the server certificate. In some cases (self-signed certs, some corporate proxy servers), the verification will be unsuccessful and sync will fail. In those cases, you can run the Trilium client with environment variable `NODE_TLS_REJECT_UNAUTHORIZED` set to `0`: + +```text-plain +export NODE_TLS_REJECT_UNAUTHORIZED=0 +``` + +TLS certificate won't be verified and simply accepted as it is. **You need to be aware that this will degrade the security of sync process significantly and open your setup to MITM attacks. It's strongly recommended to use a valid signed server certificate.** + +Newer Trilium versions contain this in a script called `trilium-no-cert-check.sh`. + +Conflict resolution +------------------- + +You can sometimes encounter a situation where you edit the same note in multiple instances before the note changes are synchronized. + +Trilium handles this situation by just picking up the newer change and discarding the older change. The older change should still be visible in [note revisions](note-revisions.md), so it should be possible to recover any data lost in conflict resolution. + +Hash check +---------- + +After each completed sync, Trilium computes a hash of all synced data on both client and sync server. If there's a difference, something went wrong and Trilium will run an automatic recovery mechanism. diff --git a/Wiki/task-manager.md b/Wiki/task-manager.md new file mode 100644 index 0000000..67a5c5b --- /dev/null +++ b/Wiki/task-manager.md @@ -0,0 +1,65 @@ +# Task-manager +Task Manager is a [promoted attributes](promoted-attributes.md) and [scripts](scripts.md) showcase present in the [demo document](document.md). + +Demo +---- + +![](images/task-manager.png) + +Task Manager manages outstanding (TODO) tasks and finished tasks (non-empty doneDate attribute). Outstanding tasks are further categorized by location and arbitrary tags - whenever you change tag attribute in the task note, this task is then automatically moved to appropriate location. + +Task Manager also integrates with [day notes](day-notes.md) - notes are [cloned](cloning-notes.md) into day note to both todoDate note and doneDate note (with [prefix](tree-concepts.md) of either "TODO" or "DONE"). + +Implementation +-------------- + +New tasks are created in the TODO note which has `~child:template` [relation](attributes.md) (see [attribute inheritance](attribute-inheritance.md)) pointing to the task template. + +### Attributes + +Task template defines several [promoted attributes](promoted-attributes.md) - todoDate, doneDate, tags, location. Importantly it also defines `~runOnAttributeChange` relation - [event](events.md) handler which is run on attribute change. This [script](scripts.md) handles when e.g. we fill out the doneDate attribute - meaning the task is done and should be moved to "Done" note and removed from TODO, locations and tags. + +### New task button + +There's also "button" note which contains simple script which adds a button to create new note (task) in the TODO note. + +```text-plain +api.addButtonToToolbar({ + title: 'New task', + icon: 'check', + shortcut: 'alt+n', + action: async () => { + // creating notes is backend (server) responsibility so we need to pass + // the control there + const taskNoteId = await api.runOnBackend(async () => { + const todoRootNote = await api.getNoteWithLabel('taskTodoRoot'); + const {note} = await api.createNote(todoRootNote.noteId, 'new task', ''); + + return note.noteId; + }); + + // we got an ID of newly created note and we want to immediatelly display it + await api.activateNewNote(taskNoteId); + } +}); +``` + +### CSS + +In the demo screenshot above you may notice that TODO tasks are in red color and DONE tasks are green. + +This is done by having this CSS [code note](code-notes.md) which defines extra CSS classes: + +```text-plain +span.fancytree-node.todo .fancytree-title { + color: red !important; +} + +span.fancytree-node.done .fancytree-title { + color: green !important; +} +``` + +This [code note](code-notes.md) has `#appCss` [label](attributes.md) which is recognized by Trilium on startup and loaded as CSS into the application. + +Second part of this functionality is based in event handler described above which assigns `#cssClass` label to the task to either "done" or "todo" based on the task status. diff --git a/Wiki/template.md b/Wiki/template.md new file mode 100644 index 0000000..e7e8cf1 --- /dev/null +++ b/Wiki/template.md @@ -0,0 +1,42 @@ +# Template +Template is a note which serves as a kind of "template" for other kind of notes (let's call them instance notes). + +Assignment of a template relation to a note brings these three effects: + +* all attributes from the template note are [inherited](attribute-inheritance.md) to the instance notes + * note that even attributes with `#isInheritable=false` are inherited to the instance notes, but only inheritable attributes are then inherited to the children of instance notes +* note content is copied from the template note to the instance note (if the instance note content is empty at the time of template attribute assignment) +* all template's children notes are deep-duplicated to the instance note + +Example +------- + +A typical example would be a "Book" template note, which will: + +* define some [promoted attributes](promoted-attributes.md) - e.g. publication year, author etc +* you can also create kind of outline of the book review in the note text - e.g. themes, conclusion etc. .. +* you can also create child notes for e.g. highlights, summary etc. + +![](images/template.png) + +Instance note +------------- + +And then we have instance note - this note has a [relation](attributes.md) to the "Book" template note which will cause that the template note text is used to initialize the instance note text and all attributes from the template note are inherited to the instance note. + +You can create an instance note (i.e. note which uses a template) through the UI like this: + +![](api/images/qGovjbsV4FPX/template-create-instance-note.) + +For the template to appear in the menu, the template note needs to have `#template` label (don't mistake it with `~template` relation which points from the instance note to the template note). If you use [workspaces](workspace.md), you can alternatively mark templates with `#workspaceTemplate` which will display them only in the workspace. + +You can also add/change template notes after the note is created, simply create a relation `~template` pointing to the desired template note. + +Other remarks +------------- + +From the visual perspective, template can define a `#iconClass` and `#cssClass` attributes so that all e.g. books are shown with a particular icon and CSS style. + +You can check out the concept in the [demo document](document.md)| in e.g. [Relation map](relation-map.md), [Task manager](task-manager.md) or [Day notes](day-notes.md). + +See also [default note title](default-note-title.md) which allows you to create templates for note titles. Note templates and title templates can be combined by creating a `#titleTemplate` for a template note. diff --git a/Wiki/text-notes.md b/Wiki/text-notes.md new file mode 100644 index 0000000..9040dcd --- /dev/null +++ b/Wiki/text-notes.md @@ -0,0 +1,107 @@ +# Text-notes +Trilium uses awesome [CKEditor 5](https://ckeditor.com/ckeditor-5/) as its editing component. + +Formatting +---------- + +Trilium text note interface doesn't show any toolbars or formatting options by default, these needs to be brought up by: + +1. selecting text will bring up an inline toolbar: + +![](api/images/voFa4y9vMkRi/text-notes-formatting-inline.p) + +1. clicking on the block toolbar: + +![](api/images/aQT4C1G1rjUk/text-notes-formatting-block.pn) + +Read only vs. editing mode +-------------------------- + +Text notes are normally opened in edit mode, however there are two cases when they are open in read-only mode: + +* they are long and thus would take time to load so by default we open them as read only which is much quicker +* or the note has `readOnly` [label](attributes.md) + +In both cases, it is possible to switch to editable mode again. + +General Formatting +------------------ + +Trilium uses the CKEditor, so any formatting that the CKEditor supports should be available in Trilium. For example: + +**Bold** – Type `**text**` or `__text__` + +_Italic_ – Type `*text*` or `_text_` + +`Code` – Type \`text\` + +~Strikethrough~ – Type `~~text~~` + +### Lists + +* Bulleted list – Start a line with `*` or `-` followed by a space + +1. Numbered list – Start a line with `1.` or `1)` followed by a space + +\[ \] To-do list – Start a line with `[ ]` or `[x]` followed by a space to insert an unchecked or checked list item, respectively + +### Blocks + +> Block quote – Start a line with `>` followed by a space + +`Multi-line Code block` – Start a line with \`\`\` + +### Other + +Headings – Start a line with `##` or `###` followed by a space to create a heading 1, heading 2, or heading 3 (up to heading 6 if options defines more headings) + +Note: Trilium only accepts headings with `##` and more because `#` is reserved for the title + +Horizontal line – Start a line with `---` +----------------------------------------- + +Markdown & Autoformat +--------------------- + +CKEditor supports markdown-like editing experience. It recognizes syntax and automatically converts it to rich text. See it in action: + +![](images/autoformat.gif) + +Complete documentation for this feature is available in [CKEditor documentation](https://ckeditor.com/docs/ckeditor5/latest/features/autoformat.html). + +If the autoformat is not desirable for what you just wrote, you can press `CTRL-Z` which will un-autoformat the text to its original form. + +Note that the use of `#` for Heading1 style is not supported because the editor assumes that is used for the title, start with `##` for Heading2. Explanation [here](https://ckeditor.com/docs/ckeditor5/latest/features/headings.html#heading-levels). + +Math support +------------ + +Trilium provides Math support with the help of KaTex: + +![](images/math.gif) + +Cut selection to sub-note +------------------------- + +One of the common situations in Trilium is when you're editing a document, and it gets somewhat large, so you start splitting it up into sub-notes - the process is essentially like this: + +* select the desired piece of text and cut it into clipboard +* create new sub-note & give it name +* paste the content from clipboard into sub-note + +Trilium provides a way to automate this: + +![](images/cut-to-subnote.gif) + +You can notice how heading "Formatting" is automatically detected and new sub-note is named "Formatting". + +It is also possible to assign a keyboard shortcut for this action. + +Include note +------------ + +Text notes can "include" another note as a read only widget. This can be useful for e.g. including a dynamically generated chart (from scripts & "render HTML" note) or other more advanced use cases. + +This functionality is available in the block toolbar icon. + +![image](images/Text-notes%20image.png) diff --git a/Wiki/theme-gallery.md b/Wiki/theme-gallery.md new file mode 100644 index 0000000..e58fa93 --- /dev/null +++ b/Wiki/theme-gallery.md @@ -0,0 +1,19 @@ +# Theme-Gallery +Theme Gallery +------------- + +These are user-created themes which were made publicly available: + +| | | +| --- | --- | +| [Midnight](https://github.com/tobealive/trilium-midnight-theme)
👤 [tobealive](https://github.com/tobealive) ![](images/Theme-Gallery%20image.jpg) | [EOTE](https://github.com/tobealive/trilum-eote-theme)
👤 [tobealive](https://github.com/tobealive) ![](images/Theme-Gallery%20preview.jpg) | +| [Trilium Themes](https://github.com/Abourass/TriliumThemes)
👤 [Abourass](https://github.com/Abourass)
![](https://camo.githubusercontent.com/ec9eb12d0f9792a93a87ff2d50c8e0ffafd42359878885e9e8d6498ec34510fe/68747470733a2f2f692e696d6775722e636f6d2f3666466e4d75422e706e67)
![](https://camo.githubusercontent.com/745dd535b982e24b305b35e7ed42d3b4d4dcefac9ae8bd1ed9cceda83b5d1d8a/68747470733a2f2f692e696d6775722e636f6d2f7a4873513363792e706e67) ![](https://camo.githubusercontent.com/8dfbcc44a82f8780d8e2f4e4621b9447f499db2667dce9a220393def28e384dd/68747470733a2f2f692e696d6775722e636f6d2f444d5437784f702e706e67) ![](https://camo.githubusercontent.com/461416d49050e9e4415e4fe5315e2ea6987485d01a624c6d23203f78be33864b/68747470733a2f2f692e696d6775722e636f6d2f616852573667682e706e67) | [MaterialDark](https://github.com/ZMonk91/Material-Dark-Trilium)
👤 [ZMonk91](https://github.com/ZMonk91)
![](https://camo.githubusercontent.com/3486f3d96d823468163a5f968b4b201254b6fd06164321551880c3de6353eeed/68747470733a2f2f692e696d6775722e636f6d2f5a65584635474c2e706e67) | +| [lightslategray](https://github.com/jaroet/trilium-theme-lightslategray)
👤 [jaroet](https://github.com/jaroet)
![](api/images/tHaPJx9C6kS7/Theme-Gallery_lightslategray.p) | [melon-4](https://github.com/raphwriter/trilium-theme-melon)
👤 [raphwriter](https://github.com/raphwriter)
![](images/Theme-Gallery%20scrn4%2001.png) | +| [Neon\_Dark](https://github.com/Engr-AllanG/trilium-themes)
👤 [Engr-AllanG](https://github.com/Engr-AllanG)
![](images/Theme-Gallery%20Neon%20Dark%20Demo%20v.jpeg) | [Coder\_Dark](https://github.com/Engr-AllanG/trilium-themes)
👤 [Engr-AllanG](https://github.com/Engr-AllanG)
![](images/Theme-Gallery%20Trilium%20theme%20co.png) | +| [velvet](https://github.com/idelem/trilium-theme-velvet)
👤 [idelem](https://github.com/idelem)
![](api/images/DXlmWzL5ZGvE/Theme-Gallery_trilium-velvet2.) | [Dark Plus](https://github.com/SADAVA/trilium-notes-theme-dark-plus)
👤 [SADAVA](https://github.com/SADAVA)
![](images/Theme-Gallery%20Screenshot.png) | +| [Solarized](https://github.com/WKSu/trilium-solarized-theme)
👤 [WKSu](https://github.com/WKSu)
![](images/Theme-Gallery%20image.png) | [Nord](https://github.com/en3r0/Trilium-Nord-Theme)
👤 [en3r0](https://github.com/en3r0)
![](images/1%20Theme-Gallery%20image.png) | +| [Bear Note Light](https://github.com/AllanZyne/trilium-bear-theme)
👤 [AllanZyne](https://github.com/AllanZyne)
![](images/Theme-Gallery%20bear-white.png) | [Bear Note Dark](https://github.com/AllanZyne/trilium-bear-theme)
👤 [AllanZyne](https://github.com/AllanZyne)
![](images/Theme-Gallery%20bear-dark.png) | +| [Miku Hatsune](https://github.com/Sebiann/miku-hatsune-trilium-theme)
👤 [Sebiann](https://github.com/Sebiann)
![](images/2%20Theme-Gallery%20image.png) | [Midnight](https://github.com/cwilliams5/Midnight-Trilium-Dark-Mode)
👤 [cwilliams5](https://github.com/cwilliams5)
![](images/Theme-Gallery%20midnight.png) | +| [Blue](https://github.com/SiriusXT/trilium-theme-blue) (light)
👤 [SiriusXT](https://github.com/SiriusXT)
![](images/Theme-Gallery%20screenshot1.png) | [Blue](https://github.com/SiriusXT/trilium-theme-blue) (dark)
👤 [SiriusXT](https://github.com/SiriusXT)
![](images/Theme-Gallery%20screenshot2.png) | + +If you would like to add your theme to this gallery, write a new post in [👐 Show and tell](https://github.com/TriliumNext/Notes/discussions/categories/show-and-tell). diff --git a/Wiki/themes.md b/Wiki/themes.md new file mode 100644 index 0000000..4e56024 --- /dev/null +++ b/Wiki/themes.md @@ -0,0 +1,113 @@ +# Themes +Trilium by default comes with few color themes, with white being the default. To switch to dark theme, you just need to go to Options (top-left - it's the app icon) -> Appearance tab and change the theme. + +This is what it looks like: + +![](images/dark-theme.png) + +Custom CSS themes +----------------- + +Trilium provides a concept of custom user theme. You can make yourself one by creating a CSS [code note](code-notes.md) and annotating it with `#appTheme=my-theme-name` [label](attributes.md). + +You can see an example of what you can put there below: + +```text-plain +@font-face { + font-family: 'Raleway'; + font-style: normal; + font-weight: 400; + src: url('/custom/fonts/raleway.woff2') format('woff2'); +} + +:root { + --main-font-family: 'Raleway' !important; + --main-font-size: normal; + --tree-font-family: inherit; + --tree-font-size: normal; + --detail-font-family: inherit; + --detail-font-size: normal; + --detail-text-font-family: 'Garamond' !important; + + --main-background-color: #404552; + --main-text-color: #AFB8C6; + --main-border-color: #AFB8C6; + --accented-background-color: #383C4A; + --more-accented-background-color: #2F343F; + --header-background-color: #383C4A; + --button-background-color: #2F343F; + --button-disabled-background-color: #404552; + --button-border-color: #333; + --button-text-color: #AFB8C6; + --button-border-radius: 2px; + --primary-button-background-color: #6c757d; + --primary-button-text-color: white; + --primary-button-border-color: #6c757d; + --muted-text-color: #86919F; + --input-text-color: #AFB8C6; + --input-background-color: #404552; + --hover-item-text-color: white; + --hover-item-background-color: #4877B1; + --active-item-text-color: white; + --active-item-background-color: #4877B1; + --menu-text-color: #AFB8C6; + --menu-background-color: #383C4A; + --tooltip-background-color: #383C4A; + --link-color: lightskyblue; + --modal-background-color: #404552; + --modal-backdrop-color: black; + --scrollbar-border-color: rgba(175, 184, 198, 0.5); +} + +body .note-detail-text { + font-size: 120%; +} + +body .CodeMirror { + filter: invert(100%) hue-rotate(180deg); +} +``` + +We define a custom font (provided by [custom request handler](custom-request-handler.md)) and then just define a bunch of CSS variables. These variables are then used in Trilium's CSS stylesheets. You can also use standard CSS selectors for further customization (open dev tools using `CTRL-SHIFT-I` to help with that), but keep in mind that HTML structure can change in future releases which might break your selectors. For that reason it is better to restrict yourself to use CSS variables as much as possible. + +To activate your custom theme, go to Options -> Appearance. In the select box you should see all notes (themes) labeled with `appTheme`. + +If you make a change to your theme, you should reload the frontend by pressing `CTRL-R` so the changes will take effect. + +CSS themes can be exported in .tar archive and shared to other users. Importing CSS themes from untrusted sources is not advised since the archive can also contain executable [scripts](scripts.md) which could be potentially harmful. + +You can find an example user theme _Steel Blue_ in the [demo document](document.md) + +![](images/steel-blue.png) + +Custom CSS +---------- + +Trilium also allows you to create custom CSS not associated with a theme. This can be useful in the context of [scripting](scripts.md) where you may want to e.g. change colors of notes in the tree (as used in [Task manager](task-manager.md)). + +To do this, just create a [code note](code-notes.md) with CSS type, put your custom CSS code into the note's content and create "appCss" [label](attributes.md). When Trilium frontend starts, all notes with "appCss" label are appended in the style element of the Trilium HTML page. + +Once you made your changes, you can reload the Trilium frontend by pressing CTRL-R after which the changes will take effect. + +![](images/app-css.png) + +Styling the tree +---------------- + +If you want to give some specific notes special styling in the tree, you can give them `cssClass` [label](attributes.md) which is then put into the node representing given note in the tree. + +There's also an `iconClass` using which you can define custom icons for notes in the tree - you can either use supplied ones from [boxicons](https://boxicons.com/) (e.g. `bx bx-home`) or you can define your own CSS classes. Some of those are actually different. So you have `bx bxs-piano`for instance instead of `bx bx-piano`. On the boxicons site, you can find out, looking at the font tab, after u opened a file, how its called. + +`iconClass` and `cssClass` are especially powerful when used with [template](template.md). + +You can also create specific styling for given note types (and mime types). For example, file note containing PNG image will have these classes in the tree: `type-image mime-image-png`. + +User-provided themes +-------------------- + +Some users made their custom themes publicly available. For a gallery of user themes, see [Theme gallery](theme-gallery.md). + +Asset path +---------- + +In case you want to use some built-in assets like `/assets/v0.57.0-beta/images/icon-grey.png` but want to avoid specifying the version, you can use a `vX` alias - in this case `/assets/vX/images/icon-grey.png`. diff --git a/Wiki/tls-configuration.md b/Wiki/tls-configuration.md new file mode 100644 index 0000000..bf6bd33 --- /dev/null +++ b/Wiki/tls-configuration.md @@ -0,0 +1,42 @@ +# TLS-configuration +TLS configuration is required for \[\[server installation\]\]. The page below describes steps to set up TLS in Trilium itself. You might also opt for TLS termination using some reverse proxy (e.g. nginx), in that case follow a [guide like this](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-20-04). + +First thing to do is to get a TLS certificate. You have two options: + +* Recommended - get TLS certificate signed by root certificate authority. For personal usage, the best choice is [Let's encrypt](https://letsencrypt.org). It's free, automated and easy. You can take a look at Certbot for automatic TLS setup. +* generate your own self-signed certificate. You will have extra trouble with importing the certificate into all machines from which you connect to the server installation so this is not recommended. + +Modifying config.ini +-------------------- + +Now that you have your certificate, we need to modify `config.ini` in the \[\[data directory\]\] so that Trilium will use it: + +```text-plain +[Network] +port=8080 +# true for TLS/SSL/HTTPS (secure), false for HTTP (unsecure). +https=true +# path to certificate (run "bash bin/generate-cert.sh" to generate self-signed certificate). Relevant only if https=true +certPath=/[username]/.acme.sh/[hostname]/fullchain.cer +keyPath=/[username]/.acme.sh/[hostname]/example.com.key +``` + +Above is only example of how this is set up on my environment when I generated the certificate using Let's encrypt acme utility. Your paths may be completely different. (Note that if you are using a Docker installation, these paths should be in a volume or other path understood by the docker container, e.g., /home/node/trilium-data/\[DIR IN DATA DIRECTORY\].) + +After you set this up, you may restart Trilium and now visit the hostname with "https". + +Self-signed certificate +----------------------- + +If you need to use a self-signed certificate for your server instance, the desktop instance won't trust it. + +Currently the only way to make this work is by disabling certificate validation by setting this environment variable (for Linux): + +```text-plain +export NODE_TLS_REJECT_UNAUTHORIZED=0 +trilium +``` + +Trilium comes with scripts to start Trilium in this mode, e.g. `trilium-no-cert-check.bat` for Windows. + +\*\* Note that disabling TLS certificate validation is insecure, so do it only if you're sure you know what you're doing! \*\* diff --git a/Wiki/tree-concepts.md b/Wiki/tree-concepts.md new file mode 100644 index 0000000..61484c7 --- /dev/null +++ b/Wiki/tree-concepts.md @@ -0,0 +1,28 @@ +# Tree concepts +This page describes some basic concepts related to the tree structure of notes in Trilium. + +Note +---- + +Note is a central entity in Trilium. See [Note](note.md) for details. + +Branch +------ + +Branch describes note placement in the note tree - in essence it's a tuple of parentNoteId and noteId which says that given note is placed as a child into this parent note. + +Each note can have more than one such branches, in other words any note can have multiple placements in the tree. For lack of better word we call this "[cloning](cloning-notes.md)". + +Prefix +------ + +Prefix is branch (placement) specific title prefix for the note. Let's say you have your note placed into two different places in the tree, but you want to change the title a bit in one of the placements. For this you can use prefix. + +To edit prefix, right-click on a note in the tree pane and choose "Edit branch prefix". + +Prefix is not part of the note itself and thus is not encrypted when the note is protected. That can be useful when you want to keep part of the title in the tree visible even when protected for easier orientation. + +Subtree +------- + +Subtree is a set of notes consisting of a particular note (subtree root) and all its children, children of these children (= all its descendants). Some operations work on subtrees (e.g. export). diff --git a/Wiki/tree-manipulation.md b/Wiki/tree-manipulation.md new file mode 100644 index 0000000..a177450 --- /dev/null +++ b/Wiki/tree-manipulation.md @@ -0,0 +1,26 @@ +# Tree manipulation +This page describes how you can manipulate the note tree - specifically moving notes. + +Drag and drop +------------- + +You can manipulate the tree simply by dragging and dropping notes as you can see in the demo: + +![](images/drag-and-drop.gif) + +Keyboard manipulation +--------------------- + +Trilium provides fast keyboard based manipulation with following [shortcuts](keyboard-shortcuts.md): + +* `CTRL-UP` and `CTRL-DOWN` - move note up or down in the order +* `CTRL-LEFT` - move note upwards in the hierarchy by changing a note's parent to note's parent's parent. +* `CTRL-RIGHT` - move note downwards in the hierarchy by setting parent to the note currently above (this is a bit hard to explain - it's best to see a demo or try it for yourself) +* `LEFT` and `RIGHT` expands and collapses a sub-tree + +![](images/move-note-with-keyboard.gif) + +Context menu +------------ + +You can also move notes with familiar cut & paste from context menu or associated keyboard [shortcuts](keyboard-shortcuts.md) `CTRL-X` (cut) and `CTRL-V` (paste). diff --git a/Wiki/troubleshooting.md b/Wiki/troubleshooting.md new file mode 100644 index 0000000..38b00fb --- /dev/null +++ b/Wiki/troubleshooting.md @@ -0,0 +1,90 @@ +# Troubleshooting +Trilium is currently beta quality software, so it's quite expected there will be some bugs. + +General quickfix +---------------- + +You guessed it - it's restart. + +If there's a UI problem, it usually means that the Trilium frontend got into an inconsistent state and is acting up. The easiest way to fix it is to reload the application - just press `CTRL-R` and frontend will be reloaded. + +If this still doesn't help, or you suspect it's actually a backend issue, you can restart the whole application - in case of desktop (Electron) build, you just close the window and re-open it again. + +Broken note crashes Trilium +--------------------------- + +Sometimes a particular problem can cause issues for Trilium (e.g. render note with faulty script) and causes Trilium to crash. But since Trilium will normally try to load previously open notes, it will attempt to load again the note, causing the crash again. + +To break out of this vicious cycle, you can specify `TRILIUM_START_NOTE_ID` environment variable, which will reset the open tabs to only one with the specified note ID (just use `root`). In linux you could use it like this: + +```text-plain +TRILIUM_START_NOTE_ID=root ./trilium +``` + +Alternatively, you can also start up Trilium in a "safe mode" which will reset the current note to root: + +```text-plain +TRILIUM_SAFE_MODE=true ./trilium +``` + +Broken script prevents application startup +------------------------------------------ + +If you experiment with scripting, it might happen that you create a script which crashes the whole Trilium. That's even worse if you set it as a startup script or in an active [custom widget](custom-widget.md). + +In such cases you can start Trilium in "safe mode" which will not execute any custom scripts: + +```text-plain +TRILIUM_SAFE_MODE=true ./trilium +``` + +Depending on the Trilium distribution, there are also ready made scripts for this: `trilium-safe-mode.bat` and `trilium-safe-mode.sh`. + +Once Trilium starts up, find the note which caused the crash and fix it/delete it. + +Sync and consistency checks +--------------------------- + +Trilium periodically checks logical consistency of the database (e.g. that every note should have a parent). If some inconsistency is detected, the user is notified on the UI about the inconsistency. + +In such case, it is recommended to file a bug report and attach anonymized database (see below). + +Restoring backup +---------------- + +Trilium makes regular automatic backup, so When things go really bad we might need the last option - [restore backup](backup.md). + +Forgotten username/password +--------------------------- + +In case you forgot your password, this means that: + +* your protected notes are forever lost - they cannot be decrypted without the password +* normal (unprotected) notes are recoverable. Read below to see how. + +To be able to change username/password and thus recover your unprotected notes, you need to get access to the [document](document.md) file in a [data directory](data-directory.md). You then need to open the `document.db` file with SQLite client (command line or e.g. [DB Browser](https://sqlitebrowser.org/)) and execute following queries: + +```text-plain +UPDATE options SET value = 'your_username' WHERE name = 'username'; -- feel free to change 'your_username' to your desired username +UPDATE options SET value = '77/twC5O00cuQgNC63VK32qOKKYwj21ev3jZDXoytVU=' WHERE name = 'passwordVerificationSalt'; +UPDATE options SET value = '710BMasZCAgibzIc07X4P9Q4TeBd4ONnqJOho+pWcBM=' WHERE name = 'passwordDerivedKeySalt'; +UPDATE options SET value = 'Eb8af1/T57b89lCRuS97tPEl4CwxsAWAU7YNJ77oY+s=' WHERE name = 'passwordVerificationHash'; +UPDATE options SET value = 'QpC8XoiYYeqHPtHKRtbNxfTHsk+pEBqVBODYp0FkPBa22tlBBKBMigdLu5GNX8Uu' WHERE name = 'encryptedDataKey'; +``` + +After executing the changes, don't forget to commit/write the changes! + +This will set the password to "password". You can use that to login to the application again. + +If you already had protected notes (which are not unrecoverable), I recommend deleting them or alternatively export the unprotected notes, delete the document.db and start anew. + +If you decide to continue using the existing document file, don't forget to change your password (Options -> Change password). + +Reporting bugs +-------------- + +It's a great help to send bug reports. Here are some tips where to look at: + +Trilium uses GitHub issues - so please send your reports here: [https://github.com/TriliumNext/Notes/issues](https://github.com/TriliumNext/Notes/issues) + +Check [error logs](error-logs.md) page for info how to provide the necessary info. diff --git a/Wiki/upgrading-trilium.md b/Wiki/upgrading-trilium.md new file mode 100644 index 0000000..e2aa0ca --- /dev/null +++ b/Wiki/upgrading-trilium.md @@ -0,0 +1,22 @@ +# Upgrading Trilium +Topic of this page is upgrading Trilium from one version to another. + +How to upgrade +-------------- + +Trilium does not have a built-in auto upgrade - all upgrades have to be done manually. How to do this depends on the installation method: + +* for [docker server installation](docker-server-installation.md) - pull the image of the newer version and restart +* for all others you need to download new version of the release artifact of your choice from the [release page](https://github.com/TriliumNext/Notes/releases/latest) and replace existing version of the application - i.e. rename/delete the old directory and extract the archive of the new version + +Document compatibility and migration +------------------------------------ + +During Trilium startup, [document](document.md) will be checked whether it conforms to the version supported by the application. In case the document is in the old version, Trilium will automatically migrate it to the new version. This will then mean that the document will not be readable anymore by the older versions of Trilium. In case you want to go back to the old version of the document and Trilium, you can restore the [backed up](backup.md) `backup-before-migration.db` which is created before every migration. + +Sync compatibility +------------------ + +[Synchronization](synchronization.md) protocol is versioned and all members of the sync cluster need to talk in the same protocol version. Therefore, when you are upgrading from one version to another, it might be necessary to upgrade all instances in the cluster. + +Change in protocol version is usually indicated on a release page. diff --git a/Wiki/web-clipper.md b/Wiki/web-clipper.md new file mode 100644 index 0000000..1343c6b --- /dev/null +++ b/Wiki/web-clipper.md @@ -0,0 +1,42 @@ +# Web-clipper +![](images/Web-clipper%20chrome-trilium-web.png) + +Trilium Web Clipper is a web browser extension which allows user to clip text, screenshots, whole pages and short notes and save them directly to Trilium Notes. + +Project is hosted [here](https://github.com/zadam/trilium-web-clipper). Firefox and Chrome are supported browsers, but the chrome build should work on other chromium based browsers as well. + +Functionality +------------- + +* select text and clip it with context menu (right click) +* click on an image or link and save it through context menu +* save whole page from the popup or context menu +* save screenshot (with crop tool) from either popup or context menu +* create short text note from popup + +Trilium will save these clippings as a new child note under a "clipper inbox" note. Clipper inbox is: + +* if there's a note with [label](attributes.md) `clipperInbox`, then this note is used as parent for the clipped notes +* otherwise, [day note](day-notes.md) is used as a parent + +If there's multiple clippings from the same page (and on the same day), then they will be added to the same note. + +Get it +------ + +Extension is available from: + +* [Project release page](https://github.com/zadam/trilium-web-clipper/releases) - .xpi for Firefox and .zip for Chromium based browsers. +* [Chrome Web Store](https://chrome.google.com/webstore/detail/trilium-web-clipper/dfhgmnfclbebfobmblelddiejjcijbjm?hl=en&authuser=0) + +Configuration +------------- + +The extension needs to connect to a running Trilium instance. By default, it scans a port range on the local computer to find a desktop Trilium instance. + +It's also possible to configure [server](server-installation.md) address for cases when the desktop application is not currently running. + +Username +-------- + +Older versions of Trilium (before 0.50) required username & password to authenticate, but this was reduced to just password. Web Clipper UI still contains the username field, just use arbitrary string. diff --git a/Wiki/weight-tracker.md b/Wiki/weight-tracker.md new file mode 100644 index 0000000..7500867 --- /dev/null +++ b/Wiki/weight-tracker.md @@ -0,0 +1,73 @@ +# Weight-tracker +Weight Tracker is a [Script API](script-api.md) showcase present in the [demo document](document.md). + +[Day notes](day-notes.md) shows (among others) how we have "weight" [promoted attribute](promoted-attributes.md) in the day note [template](template.md). This then aggregates the data and shows a nice chart of weight change in time. + +Demo +---- + +![](images/weight-tracker.png) + +How to remove Weight Tracker button from the top bar +---------------------------------------------------- + +In the link map of Weight Tracker, there is a note "Button". Open it and delete or comment out its contents. Weight Tracker button will disappear after you close and open the app. + +Implementation +-------------- + +Note "Weight Tracker" in the screenshot above is of type "Render HTML note". Such note doesn't have any useful content itself, the only purpose of it is to provide a place where some [script](scripts.md) can render some output. This script is defined in [relation](attributes.md) `renderNote` - coincidentally it's the Weight Tracker's child `Implementation`. + +This Implementation [code note](code-notes.md) then contains some HTML and JavaScript which loads all the notes with "weight" attribute and displays them in a chart. To actually render chart we're using third party library [chart.js](https://www.chartjs.org/) which is imported as an attachment (it's not built-in into Trilium). + +### JS code + +To get an idea of the script, here's the "JS code" note content: + +```text-plain +async function getChartData() { + const days = await api.runOnBackend(async () => { + const notes = api.getNotesWithLabel('weight'); + const days = []; + + for (const note of notes) { + const date = note.getLabelValue('dateNote'); + const weight = parseFloat(note.getLabelValue('weight')); + + if (date && weight) { + days.push({ date, weight }); + } + } + + days.sort((a, b) => a.date > b.date ? 1 : -1); + + return days; + }); + + const datasets = [ + { + label: "Weight (kg)", + backgroundColor: 'red', + borderColor: 'red', + data: days.map(day => day.weight), + fill: false, + spanGaps: true, + datalabels: { + display: false + } + } + ]; + + return { + datasets: datasets, + labels: days.map(day => day.date) + }; +} + +const ctx = $("#canvas")[0].getContext("2d"); + +new chartjs.Chart(ctx, { + type: 'line', + data: await getChartData() +}); +``` diff --git a/Wiki/widget-basics.md b/Wiki/widget-basics.md new file mode 100644 index 0000000..a65f1e9 --- /dev/null +++ b/Wiki/widget-basics.md @@ -0,0 +1,105 @@ +# Widget-Basics +### The Very Basics + +Based on the information from [Frontend Basics](frontend-basics.md), the most basic widget we can make looks something like this. + +```text-plain +class MyWidget extends api.BasicWidget { + get position() {return 1;} + get parentWidget() {return "left-pane"} + + doRender() { + this.$widget = $("
"); + return this.$widget; + } +} + +module.exports = new MyWidget(); +``` + +If you put this in a `JS frontend` type code note, give it the `#widget` attribute and reload the page, you'll see that it runs fine with no errors. But how can we verify it worked? Open up devtools (`cmd`+`shift`+`i`) and check for the element using `document.querySelector("#my-widget")`. If you see an element, then you're all set. If you get `undefined`, something went wrong. Double check that you gave the note the `#widget` attribute. + +Obviously, this is not the most helpful widget. It's not even a "Hello World" considering we can't actually see our element. Let's fix that. + +### Rendering UI + +Let's say that we just want to make a simple button that will show us a simple message when we click it. That should be easy enough. + +First, we need to make our HTML a bit more complex to include the button. Thankfully this is easy with [jQuery](https://jquery.com/) because we can just pass an entire HTML string to it. + +```text-plain +const template = `
`; + +class MyWidget extends api.BasicWidget { + get position() {return 1;} + get parentWidget() {return "left-pane"} + + doRender() { + this.$widget = $(template); + return this.$widget; + } +} + +module.exports = new MyWidget(); +``` + +Make that change, and reload Trilium and you should see a really ugly looking button at the top-left of the left pane conflicting with the search bar. We can make that look a lot better very easily because Trilium includes [Box Icons](https://boxicons.com). Find and pick one from there, and copy the class name that it gives you. For this tutorial, I'll be using `bx bxs-magic-wand`. I'm also going to add the classes Trilium uses for the floating buttons in the tree list since that will make sure it matches any theme we use. I'd also recommend removing the text now that we have a fancy icon. Now my template looks like this: + +```text-plain +const template = `
`; +``` + +After reloading, that already looks a little bit better. But it's still in the wrong spot. We can fix that with a little bit of css. Thankfully [BasicWidget](https://zadam.github.io/trilium/frontend_api/BasicWidget.html) allows us to do this very easily with `this.cssBlock`. + +```text-plain +const template = `
`; + +class MyWidget extends api.BasicWidget { + get position() {return 1;} + get parentWidget() {return "left-pane"} + + doRender() { + this.$widget = $(template); + this.cssBlock(`#my-widget { + position: absolute; + bottom: 40px; + left: 60px; + z-index: 1; + }`) + return this.$widget; + } +} + +module.exports = new MyWidget(); +``` + +With that change, the button should now appear at the bottom left of the tree panel near the other action buttons. + +### User Interaction + +All that's left to do is add a click listener to show that message. Thankfully the [Script API](script-api.md) has a convenient method for showing messages shown below. + +```text-plain +const template = `
`; + +class MyWidget extends api.BasicWidget { + get position() {return 1;} + get parentWidget() {return "left-pane"} + + doRender() { + this.$widget = $(template); + this.cssBlock(`#my-widget { + position: absolute; + bottom: 40px; + left: 60px; + z-index: 1; + }`) + this.$widget.find("button").on("click", () => api.showMessage("Hello World!")) + return this.$widget; + } +} + +module.exports = new MyWidget(); +``` + +Reload one last time, and go ahead and click your button. You'll get that classic Trilium toast with your `Hello World` message! diff --git a/Wiki/workspace.md b/Wiki/workspace.md new file mode 100644 index 0000000..6ebe12c --- /dev/null +++ b/Wiki/workspace.md @@ -0,0 +1,23 @@ +# Workspace +Workspace is a concept built up on top of [note hoisting](note-hoisting.md). It is based on the idea that a user has several distinct spheres of interest. An example might be "Personal" and "Work", these two spheres are quite distinct and don't interact together. When I focus on Work, I don't really care about personal notes. + +So far workspace consists of these features: + +* [note hoisting](note-hoisting.md) - you can "zoom" into a workspace subtree to focus only on the relevant notes +* easy entering of workspace: + +![](images/1%20Workspace%20image.png) + +* visual identification of workspace in tabs: + +![](images/Workspace%20image.png) + +### How to use workspaces + +Let's say you have identified the workspaces and their subtrees. Define on the root of this subtree following labels: + +* `#workspace` - Marks this note as a workspace, button to enter the workspace is controlled by this +* `#workspaceIconClass` - controls the box icon to be displayed in the tree and tabs, example `bx bx-home`. See [https://boxicons.com/](https://boxicons.com/) +* `#workspaceTabBackgroundColor` - Background color of the tab, use any CSS color format, e.g. "lightblue" or "#ddd". See [https://www.w3schools.com/cssref/css\_colors.asp](https://www.w3schools.com/cssref/css_colors.asp). +* `#workspaceCalendarRoot` - marking a note with this label will define a new per-workspace calendar. If there's no such note, the global calendar will be used. +* `#workspaceTemplate` - This note will appear in the selection of available templates when creating a new note, but only when you are currently hoisted into a workspace containing this template.