mirror of
https://github.com/zadam/trilium.git
synced 2025-11-06 05:15:59 +01:00
chore(docs): restructure developer guide for monorepo
This commit is contained in:
Elian Doran
@@ -1,6 +0,0 @@
|
||||
# Copy image reference to the clipboard
|
||||
This function is handled by `src/public/app/widgets/floating_buttons/copy_image_reference_button.js` and it supports multiple note types out of the box.
|
||||
|
||||
To enable the display of the button, simply modify `isEnabled` to add support for the new note type.
|
||||
|
||||
No other modifications should be necessary.
|
||||
@@ -1,33 +0,0 @@
|
||||
# Export diagram as SVG
|
||||
This mechanism is handled by `src/public/app/widgets/floating_buttons/svg_export_button.js`.
|
||||
|
||||
## Step 1. Enable the button
|
||||
|
||||
Modify the `isEnabled` method in `svg_export_button.js` to add support for the new note type.
|
||||
|
||||
## Step 2. Add support for exporting the image
|
||||
|
||||
The SVG export needs to be handled inside the note type implementation.
|
||||
|
||||
The first goal is to create a method to handle the <a class="reference-link" href="SVG%20rendering.md">SVG rendering</a>. Make sure to deduplicate the code if the SVG rendering is already handled.
|
||||
|
||||
```
|
||||
async renderSvg() {
|
||||
return await this.mind.exportSvg().text();
|
||||
}
|
||||
```
|
||||
|
||||
Then create an event handler to manage the SVG export:
|
||||
|
||||
```
|
||||
async exportSvgEvent({ntxId}) {
|
||||
if (!this.isNoteContext(ntxId) || this.note.type !== "mindMap") {
|
||||
return;
|
||||
}
|
||||
|
||||
const svg = await this.renderSvg();
|
||||
utils.downloadSvg(this.note.title, svg);
|
||||
}
|
||||
```
|
||||
|
||||
Make sure to modify the note type assertion at the beginning of the method. This is very important, otherwise there can be errors when navigating through multiple note types that support this button.
|
||||
@@ -1,54 +0,0 @@
|
||||
# First steps
|
||||
> **Note**: When adding or updating step titles/order, don't forget to update the corresponding list in <a class="reference-link" href="Note%20type%20checklist.md">Note type checklist</a>.
|
||||
|
||||
## Step 1. Register the note type in the server
|
||||
|
||||
Go to `src\services\note_types.ts` and add a new entry in `noteTypes` with the type ID and the default MIME type.
|
||||
|
||||
## Step 2. Register the note type in the client context menu
|
||||
|
||||
The client lists the available note types in `src\public\app\services\note_types.ts`.
|
||||
|
||||
## Step 3. Create a type widget
|
||||
|
||||
Go to `src\public\app\widgets\type_widgets` directory and create a new file corresponding to the new note type.
|
||||
|
||||
A blank implementation looks something like this:
|
||||
|
||||
## Step 4. Register the type widget
|
||||
|
||||
The type widget needs to go in `src\public\app\widgets\note_detail.ts`where there is a `typeWidgetClasses` map, mapping the type IDs with the corresponding type widget that was created at the previous step.
|
||||
|
||||
## Step 5. Add the default icon mapping
|
||||
|
||||
To set a default icon for this note type, go to `src\public\app\entities\fnote.ts` and add it to `NOTE_TYPE_ICONS`.
|
||||
|
||||
## Step 6. Add to note type selector
|
||||
|
||||
Go to `src/public/app/widgets/note_type.ts` and register the new note type in `NOTE_TYPES`.
|
||||
|
||||
## Step 7. Add the note to server allowed note types
|
||||
|
||||
This is required in order to make imports possible, otherwise they will be imported as plain text.
|
||||
|
||||
Go to `src/becca/entities/rows.ts` and add the new note type to `ALLOWED_NOTE_TYPES`.
|
||||
|
||||
## Additional changes
|
||||
|
||||
* If the widget requires a full height, it must be configured in `src\public\app\widgets\note_detail.ts` (look for `checkFullHeight`) then a `height: 100%` style can be applied to the containers to make them fit.
|
||||
* To make the note always full width (ignoring the user's content width), go to `note_wrapper` and look for the `refresh` method. There is a `toggleClass` for `full-content-width` based on the note type.
|
||||
* To allow the note source to be viewed, go to `src/public/app/widgets/buttons/note_actions.ts` and look for `this.toggleDisabled(this.$showSourceButton` in `refreshVisibility`.
|
||||
|
||||
## Final steps
|
||||
|
||||
* Update the <a class="reference-link" href="../Demo%20document.md">Demo document</a> to showcase the new note type.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Content does not appear, however it appears as hidden in the DOM
|
||||
|
||||
Type widgets do a check whenever a note is selected to determine whether the widget needs to be displayed or not, based on the note type. Make sure `getType()` is well implemented in the newly added type widget (take great care that the value is returned but also that the note type ID matches the ones registered in the previous steps):
|
||||
|
||||
```
|
||||
static getType() { return "foo"; }
|
||||
```
|
||||
@@ -1,27 +0,0 @@
|
||||
import TypeWidget from "./type_widget.js";
|
||||
|
||||
const TPL = `
|
||||
<div class="note-detail-mind-map note-detail-printable">
|
||||
</div>
|
||||
`;
|
||||
|
||||
export default class MindMapWidget extends TypeWidget {
|
||||
static getType() { return "mindMap"; }
|
||||
|
||||
doRender() {
|
||||
this.$widget = $(TPL);
|
||||
|
||||
super.doRender();
|
||||
}
|
||||
|
||||
async doRefresh(note) {
|
||||
this.$widget.html("<p>Hello</p>");
|
||||
this.$widget.show();
|
||||
}
|
||||
|
||||
async entitiesReloadedEvent({loadResults}) {
|
||||
if (loadResults.isNoteReloaded(this.noteId)) {
|
||||
this.refresh();
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,9 +0,0 @@
|
||||
# Loading data
|
||||
Data loading can be done in `doRefresh()` since it gets a reference to the note:
|
||||
|
||||
```
|
||||
const blob = await note.getBlob();
|
||||
const content = blob.getJsonContent();
|
||||
```
|
||||
|
||||
Note that `doRefresh` can sometimes be called by <a class="reference-link" href="Saving%20data%20via%20spaced%20update.md">Saving data via spaced update</a> when the user makes a changes, this has to be accounted for.
|
||||
@@ -1,49 +0,0 @@
|
||||
# Note type checklist
|
||||
The goal of this checklist is to ensure a good implementation or re-test of a note type.
|
||||
|
||||
## Implementation checklist
|
||||
|
||||
The note type widget must be created according to <a class="reference-link" href="First%20steps.md">First steps</a>:
|
||||
|
||||
* Register the note type in the server
|
||||
* Register the note type in the client context menu
|
||||
* Create a type widget
|
||||
* Register the type widget
|
||||
* Add the default icon mapping
|
||||
* Add to note type selector
|
||||
* Add the note to server allowed note types
|
||||
* Update demo document to include this new note type
|
||||
* Increase server sync version (see <a class="reference-link" href="#root/XPSyrTI07rbd/DrIXfwu9CVJP">Mindmap gets turned as file</a>).
|
||||
|
||||
## Validation checklist
|
||||
|
||||
### Ensure that the note renders properly
|
||||
|
||||
* When refreshing to a note that is already displayed
|
||||
* When going to another note and then going back
|
||||
* When creating a new note of the given type
|
||||
* Have two tabs of the same note type and switch between them
|
||||
|
||||
### Ensure data persistence
|
||||
|
||||
* Save data when modifying changes via spaced update
|
||||
|
||||
### Ensure data retrieval
|
||||
|
||||
* Go on a note of this type and refresh the page
|
||||
* Create a new note of this type while on another note of this type and ensure that the content is set properly.
|
||||
|
||||
### Set up a note preview
|
||||
|
||||
For an implementation reference, see <a class="reference-link" href="SVG%20rendering.md">SVG rendering</a>.
|
||||
|
||||
* Note preview rendering (go to parent and see note list).
|
||||
* Include note
|
||||
* Share
|
||||
* Note revisions
|
||||
|
||||
### Import/export
|
||||
|
||||
* Export & Import, making sure no data is lost in the process.
|
||||
* Remove the data folder entirely to test that the demo document is well imported on first setup.
|
||||
* Ensure that the preview also works (check the preview in the root note).
|
||||
@@ -1,72 +0,0 @@
|
||||
# SVG rendering
|
||||
For diagrams and similar note types, it makes sense to cache an SVG rendering of the content so that it can be used for:
|
||||
|
||||
* Content preview in note lists (when viewing the list of notes from the parent note).
|
||||
* Note inclusion
|
||||
* Share
|
||||
|
||||
## Step 1. Save the SVG content as an attachment
|
||||
|
||||
The first step is to obtain the SVG from the custom widget used. For example, for Mind Elixir there is an `exportSvg` method.
|
||||
|
||||
If the returned value is a `Blob`, then the underlying text can be obtained via `await blob.text()`.
|
||||
|
||||
To save the SVG as an attachment alongside the content, simply modify `getData()`:
|
||||
|
||||
```
|
||||
async getData() {
|
||||
const mind = this.mind;
|
||||
if (!mind) {
|
||||
return;
|
||||
}
|
||||
|
||||
const svgContent = await this.mind.exportSvg().text();
|
||||
return {
|
||||
content: mind.getDataString(),
|
||||
attachments: [
|
||||
{
|
||||
role: "image",
|
||||
title: "mindmap-export.svg",
|
||||
mime: "image/svg+xml",
|
||||
content: svgContent,
|
||||
position: 0
|
||||
}
|
||||
]
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
You can test this step by making a change to the note and then using the “Note attachments” option from the note menu.
|
||||
|
||||
## Step 2. Adapting the server to serve SVG attachment
|
||||
|
||||
The `src/routes/api/image.ts` route is in charge for serving the image previews of image notes, but also of custom note types such as canvases.
|
||||
|
||||
Alter the `returnImageInt` method as follows:
|
||||
|
||||
1. Add the image type to the guard condition which returns 400 for unsupported note types.
|
||||
2. Add an `if` statement to render the attachment using the correct name:
|
||||
|
||||
```
|
||||
if (image.type === "mindMap") {
|
||||
renderSvgAttachment(image, res, 'mindmap-export.svg');
|
||||
}
|
||||
```
|
||||
|
||||
## Step 3. Serve the SVG attachment for note preview
|
||||
|
||||
The client also needs tweaking to allow it to render SVG attachments by calling the previously modified server route.
|
||||
|
||||
The `src/public/app/services/content_renderer.js` file is in charge of handling the previews. To render using the image route, modify `getRenderedContent` to add the new note type to the `if` which calls `renderImage`.
|
||||
|
||||
## Step 4. Serve SVG for share
|
||||
|
||||
By default, `Note type cannot be displayed` will be displayed when trying to access the given note via a share.
|
||||
|
||||
To serve the SVG, open `src/share/content_renderer.ts` and look for `getContent`. Then add to the `if` containing `renderImage` the new note type.
|
||||
|
||||
This is not enough, as attempting to access the shared note will result in a broken image that fails with `Requested note is not a shareable image`. To solve this one, go to `src/share/routes.ts` and add a `renderImageAttachment` statement to `router.get('/share/api/images/[…])`.
|
||||
|
||||
## Step 5. Serve SVG for revisions
|
||||
|
||||
In the revisions list, to display the SVG, go to `src/public/app/widgets/dialogs/revisions.js` and look for the `renderContent` method. Simply add the note type to one of the already existing `if`s, such as the one for `canvas` and `mindMap` or `mermaid` (if the text content of the diagram should also be displayed).
|
||||
@@ -1,27 +0,0 @@
|
||||
# Saving data via spaced update
|
||||
The data persistence is achieved via the spaced update mechanism which is already present and needs to be integrated within the newly created type widgets.
|
||||
|
||||
First, the class must implement `getData`, in order to retrieve the data from the custom widget in a serialized form. As an example from the mind map implementation:
|
||||
|
||||
```
|
||||
async getData() {
|
||||
const mind = this.mind;
|
||||
if (!mind) {
|
||||
return;
|
||||
}
|
||||
|
||||
return {
|
||||
content: mind.getDataString()
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Here the content is a string containing a JSON. It is also possible to provide attachments here as well, such as <a class="reference-link" href="SVG%20rendering.md">SVG rendering</a> to provide a preview of the content.
|
||||
|
||||
Then to trigger an update, register a listener within the custom widget that calls the spaced update, for example:
|
||||
|
||||
```
|
||||
mind.bus.addListener("operation", (operation) => {
|
||||
this.spacedUpdate.scheduleUpdate();
|
||||
});
|
||||
```
|
||||
@@ -1,4 +0,0 @@
|
||||
# Build information
|
||||
* Provides context about when the build was made and the corresponding Git revision.
|
||||
* The information is displayed to the client when going in the about dialog.
|
||||
* The build information is hard-coded in `src/services/build.ts`. This file is generated automatically via `npm run update-build-info` which itself is run automatically whenever making a build in the CI, or a [local delivery](../Building%20and%20deployment/Build%20deliveries%20locally.md).
|
||||
@@ -1,2 +0,0 @@
|
||||
# attachments
|
||||
<figure class="table" style="width:100%;"><table class="ck-table-resized"><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>attachmentId</code></th><td>Text</td><td>Non-null</td><td> </td><td>Unique ID (e.g. <code>qhC1vzU4nwSE</code>)</td></tr><tr><th><code>ownerId</code></th><td>Text</td><td>Non-null</td><td> </td><td>The unique ID of a row in <a class="reference-link" href="notes.md">notes</a>.</td></tr><tr><th><code>role</code></th><td>Text</td><td>Non-null</td><td> </td><td>The role of the attachment: <code>image</code> for images that are attached to a note.</td></tr><tr><th><code>mime</code></th><td>Text</td><td>Non-null</td><td> </td><td>The MIME type of the attachment (e.g. <code>image/png</code>)</td></tr><tr><th><code>title</code></th><td>Text</td><td>Non-null</td><td> </td><td>The title of the attachment.</td></tr><tr><th><code>isProtected</code></th><td>Integer</td><td>Non-null</td><td>0</td><td><code>1</code> if the entity is <a href="../Protected%20entities.md">protected</a>, <code>0</code> otherwise.</td></tr><tr><th><code>position</code></th><td>Integer</td><td>Non-null</td><td>0</td><td>Not sure where the position is relevant for attachments (saw it with values of 10 and 0).</td></tr><tr><th><code>blobId</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td>The corresponding <code>blobId</code> from the <a class="reference-link" href="blobs.md">blobs</a> table.</td></tr><tr><th><code>dateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Localized modification date (e.g. <code>2023-11-08 18:43:44.204+0200</code>)</td></tr><tr><th><code>utcDateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Modification date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr><tr><th><code>utcDateScheduledForErasure</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td> </td></tr><tr><th><code>isDeleted</code></th><td>Integer</td><td>Non-null</td><td> </td><td><code>1</code> if the entity is <a href="../Deleted%20notes.md">deleted</a>, <code>0</code> otherwise.</td></tr><tr><th><code>deleteId</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td> </td></tr></tbody></table></figure>
|
||||
@@ -1,2 +0,0 @@
|
||||
# attributes
|
||||
<figure class="table"><table><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>attributeId</code></th><td>Text</td><td>Non-null</td><td> </td><td>Unique Id of the attribute (e.g. <code>qhC1vzU4nwSE</code>), can also have a special unique ID for <a class="reference-link" href="../Special%20notes.md">Special notes</a> (e.g. <code>_lbToday_liconClass</code>).</td></tr><tr><th><code>noteId</code></th><td>Text</td><td>Non-null</td><td> </td><td>The ID of the <a href="notes.md">note</a> this atttribute belongs to</td></tr><tr><th><code>type</code></th><td>Text</td><td>Non-null</td><td> </td><td>The type of attribute (<code>label</code> or <code>relation</code>).</td></tr><tr><th><code>name</code></th><td>Text</td><td>Non-null</td><td> </td><td>The name/key of the attribute.</td></tr><tr><th><code>value</code></th><td>Text</td><td>Non-null</td><td><code>""</code></td><td><ul><li>For <code>label</code> attributes, a free-form value of the attribute.</li><li>For <code>relation</code> attributes, the ID of the <a href="notes.md">note</a> the relation is pointing to.</li></ul></td></tr><tr><th><code>position</code></th><td>Integer</td><td>Non-null</td><td>0</td><td>The position of the attribute compared to the other attributes. Some predefined attributes such as <code>originalFileName</code> have a value of 1000.</td></tr><tr><th><code>utcDateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Modification date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr><tr><th><code>isDeleted</code></th><td>Integer</td><td>Non-null</td><td> </td><td><code>1</code> if the entity is <a href="../Deleted%20notes.md">deleted</a>, <code>0</code> otherwise.</td></tr><tr><th><code>deleteId</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td> </td></tr><tr><th><code>isInheritable</code></th><td>Integer</td><td>Nullable</td><td>0</td><td> </td></tr></tbody></table></figure>
|
||||
@@ -1,2 +0,0 @@
|
||||
# blobs
|
||||
<figure class="table"><table><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>blobId</code></th><td>Text</td><td>Non-null</td><td> </td><td>The unique ID of the blob (e.g. <code>XXbfAJXqWrYnSXcelLFA</code>).</td></tr><tr><th><code>content</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td><p>The content of the blob, can be either:</p><ul><li>text (for plain text notes or HTML notes).</li><li>binary (for images and other types of attachments)</li></ul></td></tr><tr><th><code>dateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Localized modification date (e.g. <code>2023-11-08 18:43:44.204+0200</code>)</td></tr><tr><th><code>utcDateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Modification date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr></tbody></table></figure>
|
||||
@@ -1,2 +0,0 @@
|
||||
# branches
|
||||
<figure class="table"><table><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>branchId</code></th><td>Text</td><td>Non-null</td><td> </td><td>The ID of the branch, in the form of <code>a_b</code> where <code>a</code> is the <code>parentNoteId</code> and <code>b</code> is the <code>noteId</code>.</td></tr><tr><th><code>noteId</code></th><td>Text</td><td>Non-null</td><td> </td><td>The ID of the <a href="notes.md">note</a>.</td></tr><tr><th><code>parentNoteId</code></th><td>Text</td><td>Non-null</td><td> </td><td>The ID of the parent <a href="notes.md">note</a> the note belongs to.</td></tr><tr><th><code>notePosition</code></th><td>Integer</td><td>Non-null</td><td> </td><td>The position of the branch within the same level of hierarchy, the value is usually a multiple of 10.</td></tr><tr><th><code>prefix</code></th><td>Text</td><td>Nullable</td><td> </td><td>The <a href="../Branch%20prefixes.md">branch prefix</a> if any, or <code>NULL</code> otherwise.</td></tr><tr><th><code>isExpanded</code></th><td>Integer</td><td>Non-null</td><td>0</td><td>Whether the branch should appear expanded (its children shown) to the user.</td></tr><tr><th><code>isDeleted</code></th><td>Integer</td><td>Non-null</td><td>0</td><td><code>1</code> if the entity is <a href="../Deleted%20notes.md">deleted</a>, <code>0</code> otherwise.</td></tr><tr><th><code>deleteId</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td> </td></tr><tr><th><code>utcDateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Modification date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr></tbody></table></figure>
|
||||
@@ -1,2 +0,0 @@
|
||||
# entity_changes
|
||||
<figure class="table"><table><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>id</code></th><td>Integer</td><td>Nullable</td><td> </td><td>A sequential numeric index of the entity change.</td></tr><tr><th><code>entityName</code></th><td>Text</td><td>Nullable</td><td> </td><td>The type of entity being changed (<code>attributes</code>, <code>branches</code>, <code>note_reordering</code>, etc.)</td></tr><tr><th><code>entityId</code></th><td>Text</td><td>Nullable</td><td> </td><td>The ID of the entity being changed.</td></tr><tr><th><code>hash</code></th><td>Text</td><td>Nullable</td><td> </td><td>TODO: Describe how the hash is calculated</td></tr><tr><th><code>isErased</code></th><td>Integer</td><td>Nullable</td><td> </td><td>TODO: What does this do?</td></tr><tr><th><code>changeId</code></th><td>Text</td><td>Nullable</td><td> </td><td>TODO: What does this do?</td></tr><tr><th><code>componentId</code></th><td>Text</td><td>Nullable</td><td> </td><td>TODO: What does this do?</td></tr><tr><th><code>instanceId</code></th><td>Text</td><td>Nullable</td><td> </td><td>TODO: What does this do?</td></tr><tr><th><code>isSynced</code></th><td>Integer</td><td>Nullable</td><td> </td><td>TODO: What does this do?</td></tr><tr><th><code>utcDateChanged</code></th><td>Text</td><td>Nullable</td><td> </td><td>Date of the entity change in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr></tbody></table></figure>
|
||||
@@ -1,2 +0,0 @@
|
||||
# etapi_tokens
|
||||
<figure class="table"><table><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>etapiTokenId</code></th><td>Text</td><td>Non-null</td><td> </td><td>A unique ID of the token (e.g. <code>aHmLr5BywvfJ</code>).</td></tr><tr><th><code>name</code></th><td>Text</td><td>Non-null</td><td> </td><td>The name of the token, as is set by the user.</td></tr><tr><th><code>tokenHash</code></th><td>Text</td><td>Non-null</td><td> </td><td>The token itself.</td></tr><tr><th><code>utcDateCreated</code></th><td>Text</td><td>Non-null</td><td> </td><td>Creation date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr><tr><th><code>utcDateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Modification date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr><tr><th><code>isDeleted</code></th><td>Integer</td><td>Non-null</td><td>0</td><td><code>1</code> if the entity is <a href="../Deleted%20notes.md">deleted</a>, <code>0</code> otherwise.</td></tr></tbody></table></figure>
|
||||
@@ -1,2 +0,0 @@
|
||||
# notes
|
||||
<figure class="table"><table><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>noteId</code></th><td>Text</td><td>Non-null</td><td> </td><td>The unique ID of the note (e.g. <code>2LJrKqIhr0Pe</code>).</td></tr><tr><th><code>title</code></th><td>Text</td><td>Non-null</td><td><code>"note"</code></td><td>The title of the note, as defined by the user.</td></tr><tr><th><code>isProtected</code></th><td>Integer</td><td>Non-null</td><td>0</td><td><code>1</code> if the entity is <a href="../Protected%20entities.md">protected</a>, <code>0</code> otherwise.</td></tr><tr><th><code>type</code></th><td>Text</td><td>Non-null</td><td><code>"text"</code></td><td>The type of note (i.e. <code>text</code>, <code>file</code>, <code>code</code>, <code>relationMap</code>, <code>mermaid</code>, <code>canvas</code>).</td></tr><tr><th><code>mime</code></th><td>Text</td><td>Non-null</td><td><code>"text/html"</code></td><td>The MIME type of the note (e.g. <code>text/html</code>).. Note that it can be an empty string in some circumstances, but not null.</td></tr><tr><th><code>isDeleted</code></th><td>Integer</td><td>Nullable</td><td>0</td><td><code>1</code> if the entity is <a href="../Deleted%20notes.md">deleted</a>, <code>0</code> otherwise.</td></tr><tr><th><code>deleteId</code></th><td>Text</td><td>Non-null</td><td><code>null</code></td><td> </td></tr><tr><th><code>dateCreated</code></th><td>Text</td><td>Non-null</td><td> </td><td>Localized creation date (e.g. <code>2023-11-08 18:43:44.204+0200</code>)</td></tr><tr><th><code>dateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Localized modification date (e.g. <code>2023-11-08 18:43:44.204+0200</code>)</td></tr><tr><th><code>utcDateCreated</code></th><td>Text</td><td>Non-null</td><td> </td><td>Creation date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr><tr><th><code>utcDateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Modification date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr><tr><th><code>blobId</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td>The corresponding ID from <a class="reference-link" href="blobs.md">blobs</a>. Although it can theoretically be <code>NULL</code>, haven't found any such note yet.</td></tr></tbody></table></figure>
|
||||
@@ -1,2 +0,0 @@
|
||||
# options
|
||||
<figure class="table"><table><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>name</code></th><td>Text</td><td>Non-null</td><td> </td><td>The name of option (e.g. <code>maxContentWidth</code>)</td></tr><tr><th><code>value</code></th><td>Text</td><td>Non-null</td><td> </td><td>The value of the option.</td></tr><tr><th><code>isSynced</code></th><td>Integer</td><td>Non-null</td><td>0</td><td><code>0</code> if the option is not synchronized and thus can differ between clients, <code>1</code> if the option is synchronized.</td></tr><tr><th><code>utcDateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Modification date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr></tbody></table></figure>
|
||||
@@ -1,2 +0,0 @@
|
||||
# recent_notes
|
||||
<figure class="table"><table><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>noteId</code></th><td>Text</td><td>Non-null</td><td> </td><td>Unique ID of the note (e.g. <code>yRRTLlqTbGoZ</code>).</td></tr><tr><th><code>notePath</code></th><td>Text</td><td>Non-null</td><td> </td><td>The path (IDs) to the <a href="notes.md">note</a> from root to the note itself, separated by slashes.</td></tr><tr><th><code>utcDateCreated</code></th><td>Text</td><td>Non-null</td><td> </td><td>Creation date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr></tbody></table></figure>
|
||||
@@ -1,2 +0,0 @@
|
||||
# revisions
|
||||
<figure class="table"><table><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>revisionId</code></th><td>TextText</td><td>Non-null</td><td> </td><td>Unique ID of the revision (e.g. <code>0GjgUqnEudI8</code>).</td></tr><tr><th><code>noteId</code></th><td>Text</td><td>Non-null</td><td> </td><td>ID of the <a href="notes.md">note</a> this revision belongs to.</td></tr><tr><th><code>type</code></th><td>Text</td><td>Non-null</td><td><code>""</code></td><td>The type of note (i.e. <code>text</code>, <code>file</code>, <code>code</code>, <code>relationMap</code>, <code>mermaid</code>, <code>canvas</code>).</td></tr><tr><th><code>mime</code></th><td>Text</td><td>Non-null</td><td><code>""</code></td><td>The MIME type of the note (e.g. <code>text/html</code>).</td></tr><tr><th><code>title</code></th><td>Text</td><td>Non-null</td><td> </td><td>The title of the note, as defined by the user.</td></tr><tr><th><code>isProtected</code></th><td>Integer</td><td>Non-null</td><td>0</td><td><code>1</code> if the entity is <a href="../Protected%20entities.md">protected</a>, <code>0</code> otherwise.</td></tr><tr><th><code>blobId</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td>The corresponding ID from <a class="reference-link" href="blobs.md">blobs</a>. Although it can theoretically be <code>NULL</code>, haven't found any such note yet.</td></tr><tr><th><code>utcDateLastEdited</code></th><td>Text</td><td>Non-null</td><td> </td><td><strong>Not sure how it differs from modification date.</strong></td></tr><tr><th><code>utcDateCreated</code></th><td>Text</td><td>Non-null</td><td> </td><td>Creation date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr><tr><th><code>utcDateModified</code></th><td>Text</td><td>Non-null</td><td> </td><td>Modification date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr><tr><th><code>dateLastEdited</code></th><td>Text</td><td>Non-null</td><td> </td><td><strong>Not sure how it differs from modification date.</strong></td></tr><tr><th><code>dateCreated</code></th><td>Text</td><td>Non-null</td><td> </td><td>Localized creatino date (e.g. <code>2023-08-12 15:10:04.045+0300</code>)</td></tr></tbody></table></figure>
|
||||
@@ -1,19 +0,0 @@
|
||||
# Demo document
|
||||
The demo document is an exported .zip that resides in `db/demo.zip`.
|
||||
|
||||
During on-boarding, if the user selects that they are a new user then the `demo.zip` is imported into the root note.
|
||||
|
||||
## Modifying the document
|
||||
|
||||
On a dev server, remove all your existing notes in order to ensure a clean setup. Right click → Import to note and select the .zip file in `db/demo.zip`. Make sure to disable “Safe import”.
|
||||
|
||||
After making the necessary modifications, simply export the “Trilium Demo” note as “HTML in ZIP archive” and replace `db/demo.zip` with the newly exported one.
|
||||
|
||||
## Testing the changes
|
||||
|
||||
```
|
||||
rm -r data
|
||||
npm run start-server
|
||||
```
|
||||
|
||||
And then do the on-boarding again.
|
||||
@@ -1,18 +0,0 @@
|
||||
# Docker
|
||||
To run a Docker build:
|
||||
|
||||
```
|
||||
./bin/builder-docker.sh
|
||||
```
|
||||
|
||||
To run the built Docker image:
|
||||
|
||||
```
|
||||
sudo docker run -p 8081:8080 triliumnext/notes:v0.90.6-beta
|
||||
```
|
||||
|
||||
To enter a shell in the Docker container:
|
||||
|
||||
```
|
||||
sudo docker run -it --entrypoint=/bin/sh zadam/trilium:0.63-latest
|
||||
```
|
||||
@@ -1,6 +0,0 @@
|
||||
# Hidden notes
|
||||
## Disallow adding child notes
|
||||
|
||||
1. To enforce at server level go to `services/notes.ts` and look for the `getAndValidateParent` method. Look for the `params.ignoreForbiddenParents` if statement and add it there.
|
||||
2. To hide the plus button in the note tree, go to `widgets/note_tree` in the client and look for `enhanceTitle`. Look for the if statement which starts with `!["search", "launcher"].includes(note.type)`.
|
||||
3. To disable it from the contextual menu, go to `tree_context_menu` and look for the `getMenuItems` method. There look for the `insertNoteAfter` and `insertChildNote` actions and look at their `enabled` conditions. If adding a big note type with lots of child notes, see the pattern of optinos & help (rename and augment the `notOptionsOrHelp` variable.
|
||||
@@ -1,26 +0,0 @@
|
||||
# Icons
|
||||
Icons are stored in `images` and in `images/app-icons`.
|
||||
|
||||
## Favicon
|
||||
|
||||
The favicon is served dynamically via `serve-favicon`, using the icon in `images/app-icons/win/icon.ico`.
|
||||
|
||||
## Declarative generation of icons
|
||||
|
||||
All the icons are now built off of the SVGs in the `images` directory using the `bin/create-icons.sh` script.
|
||||
|
||||
## Main images
|
||||
|
||||
These are stored in `images`:
|
||||
|
||||
<figure class="table"><table><thead><tr><th>Name</th><th>Resolution</th><th>Description</th></tr></thead><tbody><tr><td><code>icon-black.svg</code></td><td>53x40</td><td>Used by the global menu button when not hovered.</td></tr><tr><td><code>icon-color.svg</code></td><td>53x40</td><td>Used by the global menu when hovered.</td></tr><tr><td><code>icon-grey.svg</code></td><td>53x40</td><td>Used by the dark theme, in place of <code>icon-black.svg</code>.</td></tr></tbody></table></figure>
|
||||
|
||||
## App icons
|
||||
|
||||
<figure class="table"><table><thead><tr><th>Name</th><th>Resolution</th><th>Description</th></tr></thead><tbody><tr><td><code>ios/apple-touch-icon.png</code></td><td>180x180</td><td>Used as <code>apple-touch-icon</code>, but only in <code>login.ejs</code> and <code>set_password.ejs</code> for some reason.</td></tr><tr><td><code>mac/icon.icns</code></td><td>512x512</td><td>Provided as <code>--icon</code> to <code>electron-packager</code> for <code>mac-arm64</code> and <code>mac-x64</code> <a href="../Building%20and%20deployment/Build%20deliveries%20locally.md">builds</a>.</td></tr><tr><td><code>png/128x128.png</code></td><td>128x128</td><td>Used in <code>linux-x64</code> <a href="../Building%20and%20deployment/Build%20deliveries%20locally.md">build</a>, to provide an <code>icon.png</code>.</td></tr><tr><td><code>png/256x256-dev.png</code></td><td>256x256</td><td>Used by the Electron window icon, if in dev mode.</td></tr><tr><td><code>png/256x256.png</code></td><td>Used by the Electron window icon, if not in dev mode.</td></tr><tr><td><code>win/icon.ico</code></td><td><ul><li>ICO 16x16</li><li>ICO 32x32</li><li>ICO 48x48</li><li>ICO 64x64</li><li>ICO 128x128</li><li>PNG 256x256</li></ul></td><td><ul><li>Used by the <code>win-x64</code> <a href="../Building%20and%20deployment/Build%20deliveries%20locally.md">build</a>.</li><li>Used by Squirrel Windows installer for: setup icon, app icon, control panel icon</li><li>Used as the favicon.</li></ul></td></tr><tr><td><code>win/setup-banner.gif</code></td><td>640x480</td><td>Used by the Squirrel Windows installer during the installation process. Has only one frame.</td></tr></tbody></table></figure>
|
||||
|
||||
## Additional locations where the branding is used
|
||||
|
||||
* In the client, more specifically in `src/public/app/widgets/buttons/global_menu.js`, where the SVG content of the icon is directly embedded to allow styling via CSS.
|
||||
* In the <a class="reference-link" href="Demo%20document.md">Demo document</a>, as an attachment.
|
||||
* In the <a class="reference-link" href="#root/OeKBfN6JbMIq/MF99QFRe1gVy/xkj1bqW7zJwQ/t6mT72MfEzb2">CKEditor</a> build, look for `packages/ckeditor5-build-balloon-block/src/icons/trilium.svg`. Make sure not to have any `fill` overrides in the SVG as the wrong color will be used.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 233 KiB |
@@ -1,8 +0,0 @@
|
||||
# Icons on Mac
|
||||
Looks great in Finder:
|
||||
|
||||
<figure class="image"><img src="Icons on Mac_image.png"></figure>
|
||||
|
||||
Looks great in Dock:
|
||||
|
||||
<figure class="image"><img src="1_Icons on Mac_image.png"></figure>
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 233 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 748 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 7.4 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 83 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 6.5 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 250 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 7.1 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 251 KiB |
@@ -1,6 +0,0 @@
|
||||
# Adaptive icon
|
||||
<figure class="table" style="width:100%;"><table class="ck-table-resized"><colgroup><col> <col></colgroup><tbody><tr><th>Before</th><td><figure class="image"><img src="1_Adaptive icon_image.png"></figure></td></tr><tr><th>After</th><td><figure class="image"><img src="6_Adaptive icon_image.png"></figure></td></tr><tr><th>With new scale</th><td><figure class="image"><img src="4_Adaptive icon_image.png"></figure></td></tr></tbody></table></figure>
|
||||
|
||||
## Scale
|
||||
|
||||
<figure class="table" style="width:300px;"><table><tbody><tr><th>0.9</th><td style="background-color:hsl(0, 0%, 90%)"><figure class="image"><img src="2_Adaptive icon_image.png"></figure></td></tr><tr><th>0.85</th><td style="background-color:hsl(0, 0%, 90%);"><figure class="image"><img src="5_Adaptive icon_image.png"></figure></td></tr><tr><th>0.8</th><td style="background-color:hsl(0, 0%, 90%);"><figure class="image"><img src="Adaptive icon_image.png"></figure></td></tr><tr><th>0.75</th><td style="background-color:hsl(0, 0%, 90%);"><figure class="image"><img src="3_Adaptive icon_image.png"></figure></td></tr></tbody></table></figure>
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 6.8 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 716 KiB |
@@ -1,50 +0,0 @@
|
||||
# Slightly blurry icon on Mac
|
||||
Slightly blurry in extended preview on Mac
|
||||
|
||||
<figure class="image"><img src="1_Slightly blurry icon on Ma.png"></figure>
|
||||
|
||||
In the screenshot, the icon is around 650px whereas the closest image we have is 512px, so that might explain the blur. Adding an `ic10` (`1024x1024`, aka `512x512@2x` to see what happens).
|
||||
|
||||
Before:
|
||||
|
||||
```
|
||||
File: ../images/app-icons/mac/icon.icns
|
||||
ic09: 62069 bytes, png: 512x512
|
||||
```
|
||||
|
||||
After:
|
||||
|
||||
```
|
||||
File: ../images/app-icons/mac/icon.icns
|
||||
icp4: 1140 bytes, png: 16x16
|
||||
icp5: 1868 bytes, png: 32x32
|
||||
ic07: 9520 bytes, png: 128x128
|
||||
ic09: 62069 bytes, png: 512x512
|
||||
ic10: 180442 bytes, png: 512x512@2x
|
||||
```
|
||||
|
||||
Even with a 1024x1024 icon, the image is still blurry.
|
||||
|
||||
Comparing the `.icns` file from the Electron build reveals that the `.icns` file has been tampered with:
|
||||
|
||||
<figure class="table"><table><thead><tr><th>The <code>electron.icns</code> from the resulting build</th><th>The icon source</th></tr></thead><tbody><tr><td><pre><code class="language-text-plain">File: images/app-icons/mac/electron.icns
|
||||
icp4: 1140 bytes, png: 16x16
|
||||
icp5: 1868 bytes, png: 32x32
|
||||
ic07: 9520 bytes, png: 128x128
|
||||
ic09: 62069 bytes, png: 512x512
|
||||
ic10: 180442 bytes, png: 512x512@2x</code></pre></td><td><pre><code class="language-text-plain">File: images/app-icons/mac/icon.icns
|
||||
icp4: 1648 bytes, png: 16x16
|
||||
icp5: 4364 bytes, png: 32x32
|
||||
ic07: 26273 bytes, png: 128x128
|
||||
ic09: 206192 bytes, png: 512x512
|
||||
ic10: 716034 bytes, png: 512x512@2x</code></pre></td></tr></tbody></table></figure>
|
||||
|
||||
The bluriness might come from the image itself: [https://stackoverflow.com/questions/54030521/convert-svg-to-png-with-sharp-edges](https://stackoverflow.com/questions/54030521/convert-svg-to-png-with-sharp-edges)
|
||||
|
||||
Rendering with Inkscape (left) vs ImageMagick (right):
|
||||
|
||||
<figure class="image"><img src="2_Slightly blurry icon on Ma.png"></figure>
|
||||
|
||||
Now in macOS it's also rendering quite nicely:
|
||||
|
||||
<figure class="image"><img src="Slightly blurry icon on Ma.png"></figure>
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 336 KiB |
@@ -1,12 +0,0 @@
|
||||
# Removed icons
|
||||
The following icons were removed:
|
||||
|
||||
## Main images
|
||||
|
||||
These are stored in `images`:
|
||||
|
||||
<figure class="table"><table><thead><tr><th>Name</th><th>Resolution</th><th>Description</th></tr></thead><tbody><tr><td><code>icon-black.png</code></td><td>36x36</td><td>Does not appear to be used.</td></tr><tr><td><code>icon-color.png</code></td><td>36x36</td><td>Used only by some tests in <code>test-etapi</code>.</td></tr><tr><td><code>icon-grey.png</code></td><td>36x36</td><td>Does not appear to be used.</td></tr><tr><td><code>icon.svg</code></td><td>210x297</td><td>Does not appear to be used.</td></tr></tbody></table></figure>
|
||||
|
||||
## App icons
|
||||
|
||||
<figure class="table"><table><thead><tr><th>Name</th><th>Resolution</th><th>Description</th></tr></thead><tbody><tr><td><code>png/16x16-bw.png</code></td><td>16x16</td><td>Do not appear to be used.</td></tr><tr><td><code>png/16x16.png</code></td></tr><tr><td><code>png/24x24.png</code></td><td>24x24</td></tr><tr><td><code>png/32x32.png</code></td><td>32x32</td></tr><tr><td><code>png/48x48.png</code></td><td>48x48</td></tr><tr><td><code>png/64x64.png</code></td><td>64x64</td></tr><tr><td><code>png/96x96.png</code></td><td>96x96</td></tr><tr><td><code>png/512x512.png</code></td><td>512x512</td><td>Does not appear to be used.</td></tr><tr><td><code>win/setup-banner.xcf</code></td><td> </td><td>GIMP source for <code>win/setup-banner.gif</code>. Provided only for future editing.</td></tr></tbody></table></figure>
|
||||
@@ -1,94 +0,0 @@
|
||||
# Internationalisation / Translations
|
||||
During the initial development of Trilium Notes, internationalisation was not considered as it was meant to be an English-only product.
|
||||
|
||||
As the application and the user base grows, it makes sense to be able to reach out as many people as possible by providing translations in their native language.
|
||||
|
||||
The library used is [i18next](https://www.i18next.com/).
|
||||
|
||||
## Where are the translations?
|
||||
|
||||
The translations are formatted as JSON files and they are located in `src/public/translations`. For every supported locale, there is a subdirectory in which there is a `translation.json` file (e.g. `src/public/translations/en/translation.json`).
|
||||
|
||||
### Message keys
|
||||
|
||||
One important aspect is the fact that we are using a key-based approach. This means that each message is identified by an ID rather than a natural-language message (such as the default approach in gettext).
|
||||
|
||||
The key-based approach allows a hierarchical structure. For example, a key of `about.title` would be added in `translation.json` as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"about": {
|
||||
"title": "About TriliumNext Notes"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Follow the <a class="reference-link" href="Internationalisation%20%20Translations/Guidelines.md">Guidelines</a> when creating a new message.
|
||||
|
||||
### Adding a new locale
|
||||
|
||||
To add a new locale, go to `src/public/translations` with your favorite text editor and copy the `en` directory.
|
||||
|
||||
Rename the copy to the ISO code (e.g. `fr`, `ro`) of the language being translated.
|
||||
|
||||
Translations with a country-language combination, using their corresponding ISO code (e.g. `fr_FR`, `fr_BE`), has not been tested yet.
|
||||
|
||||
### Changing the language
|
||||
|
||||
Since the internationalisation process is in its early stages, there is no user-facing way to switch the language.
|
||||
|
||||
To change the language manually, edit `src/public/app/services/i18n.js` and look for the line containing `lng: "en"`. Replace `en` with the desired language code (from the ones available in `src/public/translations`).
|
||||
|
||||
## Client-side translations
|
||||
|
||||
### Component-level translations
|
||||
|
||||
Most of the client translations are present in the various widgets and layouts.
|
||||
|
||||
Translation support has to be added manually for every file.
|
||||
|
||||
The first step is to add the translation import with a relative import. For example, if we are in the `src/public/app/widgets/dialogs` directory, the import would look as follows:
|
||||
|
||||
```javascript
|
||||
import { t } from "../../services/i18n.js";
|
||||
```
|
||||
|
||||
Afterwards, simply replace the hard-coded message with:
|
||||
|
||||
```javascript
|
||||
${t("msgid")}
|
||||
```
|
||||
|
||||
where `msgid` is the key of the message being translated.
|
||||
|
||||
### Variables
|
||||
|
||||
In the translation, enclose the variables with `{{` and `}}`:
|
||||
|
||||
```
|
||||
{
|
||||
"key": "{{what}} is {{how}}"
|
||||
}
|
||||
```
|
||||
|
||||
Then pass the arguments when reading the translation:
|
||||
|
||||
```
|
||||
t('key', { what: 'i18next', how: 'great' })
|
||||
```
|
||||
|
||||
### Template-level translations
|
||||
|
||||
Templates are `.ejs` files present in `src/views`, these are used to prepare the root layout for desktop, mobile applications as well as setup (onboarding) and the shared notes view.
|
||||
|
||||
Due to using a different approach, it is not possible yet to translate those files.
|
||||
|
||||
## Server-side translations
|
||||
|
||||
Currently the server-side messages are not translatable. They will be added as a separate step.
|
||||
|
||||
## Locale/language selection
|
||||
|
||||
The language is stored as an option which is synchronized across all devices and the user is able to adjust it via Options → Appearance → Locale.
|
||||
|
||||
The options shown to the user are currently hard-coded in `src/routes/api/options.ts`, where there is a `getSupportedLocales()` function. The `id` field must match the corresponding directory in `src/public/translations` and the `name` must be the localized name of the language (so the name must be in that language, not in English).
|
||||
@@ -1,9 +0,0 @@
|
||||
# Guidelines
|
||||
* Use hierarchy whenever appropriate, try to group the messages by:
|
||||
* Modals (e.g. `about.foo`, `jump_to_note.foo`)
|
||||
* Don't duplicate messages that are very widely used.
|
||||
* One such example is `aria-label="Close"` which should go to a single message such as `modal.close` instead of being duplicated in every modal.
|
||||
* On the other hand, don't overly generalise messages. A `close` message that is used whenever the “Close” word is encountered is not a good approach since it can potentially cause issues due to lack of context.
|
||||
* Use [variable interpolation](https://www.i18next.com/translation-function/interpolation) whenever appropriate.
|
||||
* If you see multiple messages joined together only to apply add a variable such as a user-inputted value, try to join those messages together into a single message containing a variable.
|
||||
* So instead of `“Number of updates: “ + numUpdates + “.”` use `$(t("number_updates", { numUpdates }))` where the message translation would appear as `Number of updates: {{numUpdates}}.`
|
||||
@@ -1,19 +0,0 @@
|
||||
# Server translations
|
||||
* Server-side translations are managed by the same library as the client, i18next.
|
||||
* The translation files reside in the `/translations` directory, following the same convention as the client (`translations/{{lng}}/{{ns}}.json`), where the namespace is `server.json`. So for the Spanish translations we have `translations/es/server.json`.
|
||||
* Loading of translations is managed by [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend) which loads the translations directly from the file system (unlike HTTP requests like the client), at the path mentioned previously (relative to `package.json`).
|
||||
|
||||
## How to translate a string
|
||||
|
||||
Unlike the client which uses a dedicated client service, the i18next library on the server is used directly, as such:
|
||||
|
||||
```javascript
|
||||
import { t } from "i18next";
|
||||
|
||||
const translatedString = t("message.id");
|
||||
```
|
||||
|
||||
## What should be translated
|
||||
|
||||
* Avoid translating server-side logs, as those are supposed to be for debugging and as such there is no benefit in translating them.
|
||||
* Translate any user-facing message that comes from the server, such as error messages shown in the Electron application, or information such as keyboard shortcuts, note titles, etc.
|
||||
@@ -1,15 +0,0 @@
|
||||
# i18n-ally
|
||||
[`i18n-ally`](https://github.com/lokalise/i18n-ally) is a VS Code extension that aids in internationalization.
|
||||
|
||||
It is currently integrated in the project and offers features such as:
|
||||
|
||||
* Highlight, autocomplete translations.
|
||||
* Display translations inline.
|
||||
* Extract messages into translation.
|
||||
|
||||
### Extracting messages into translation
|
||||
|
||||
1. Open any .js file and select an untranslated string inside a template (`TPL`).
|
||||
2. Press Ctrl+P and look for “i18n Ally: Extract text into i18n messages”
|
||||
3. Select the first template.
|
||||
4. Select the path of translation, taking into consideration the <a class="reference-link" href="Guidelines.md">Guidelines</a> (e.g. `jump_to_note.search-for-note-by-its-name`).
|
||||
@@ -1,13 +0,0 @@
|
||||
# Launchers
|
||||
Launchers are items that are displayed in the launcher bar (left side of the screen). They are of two different types:
|
||||
|
||||
* Visible launchers: are displayed by default to the user, can be moved to the available launchers section to hide them.
|
||||
* Available launchers: can be manually added by the user from settings into the list of visible launchers.
|
||||
|
||||
## Adding a new launcher
|
||||
|
||||
Regardless of the type, new launchers are added at server level, inside `hidden_subtree.ts` file.
|
||||
|
||||
* To add a new available launcher, look for `_lbAvailableLaunchers` and add a new item to its `children`.
|
||||
* Similarly, to add a visible launcher, look for `_lbVisibleLaunchers`.
|
||||
* If you add a visible launcher, it will be available for both new and old users, since the application will identify that there is a new launcher to be added regardless of the user preference.
|
||||
@@ -1,20 +0,0 @@
|
||||
# Live reload
|
||||
## Server live reload
|
||||
|
||||
If running the server using `npm run start-server`, the server will watch for changes in `src/public` and trigger a frontend reload if that occurs.
|
||||
|
||||
## Electron live reload
|
||||
|
||||
Similarly, `npm run start-electron` supports live refresh as well.
|
||||
|
||||
However, a core difference is that Electron watches `dist/src/public` instead of `src/public` since Electron runs on its own copy of the files.
|
||||
|
||||
To ameliorate that, a separate watch script has been implemented which automatically copies files from `src/public` to `dist/src/public` whenever a change is detected. To run it:
|
||||
|
||||
```
|
||||
npm run
|
||||
```
|
||||
|
||||
## Technical details
|
||||
|
||||
* This mechanism is managed at server level by watching for changes in`services/ws.ts`.
|
||||
@@ -1,30 +0,0 @@
|
||||
# Note types
|
||||
The note type is defined by the `type` column in <a class="reference-link" href="Database/notes.md">notes</a>.
|
||||
|
||||
Possible types:
|
||||
|
||||
<figure class="table" style="width:100%;"><table class="ck-table-resized"><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Note Type</th><th><code>type</code> value</th><th>Corresponding MIME type</th><th>Content of the note's blob</th><th>Relevant attributes</th></tr></thead><tbody><tr><th>Text</th><td><code>text</code></td><td> </td><td>The HTML of the note.</td><td> </td></tr><tr><th><a href="https://github.com/zadam/trilium/wiki/Relation-map">Relation Map </a></th><td><code>relationMap</code></td><td><code>application/json</code></td><td><p>A JSON describing the note:</p><pre><code class="language-text-plain">{
|
||||
"notes": [
|
||||
{
|
||||
"noteId": "gFQDL11KEm9G",
|
||||
"x": 142,
|
||||
"y": 405
|
||||
},
|
||||
{
|
||||
"noteId": "8GcjEKyrrCgl",
|
||||
"x": 100.10406374385552,
|
||||
"y": 757.0364424520196
|
||||
}
|
||||
],
|
||||
"transform": {
|
||||
"scale": 0.3,
|
||||
"x": 480.29766098682165,
|
||||
"y": 116.83892021963081
|
||||
}
|
||||
}</code></pre></td><td>None</td></tr><tr><th><a href="https://github.com/zadam/trilium/wiki/Scripts">Render Note</a></th><td><code>render</code></td><td><code>text/html</code> or blank.</td><td>An empty blob.</td><td><code>~renderNote</code> pointing to the HTML note to render.</td></tr><tr><th>Canvas</th><td><code>canvas</code></td><td><code>application/json</code></td><td><pre><code class="language-text-plain">{
|
||||
"appState": {},
|
||||
"elemenets": {},
|
||||
"files": {},
|
||||
"type": "excalidraw",
|
||||
"version": 2
|
||||
}</code></pre></td><td>None</td></tr><tr><th>Mermaid Diagram</th><td><code>mermaid</code></td><td><code>text/mermaid</code> or <code>text/plain</code></td><td>The plain text content of the Mermaid diagram.</td><td>None</td></tr><tr><th>Book</th><td><code>book</code></td><td><code>text/html</code> or blank.</td><td>An empty blob.</td><td><ul><li><code>#viewType</code> which can be either <code>grid</code> or <code>list</code>.</li><li><code>#expanded</code></li></ul><p>both options are shown to the user via the “Book Properties” ribbon widget.</p></td></tr><tr><th>Web View</th><td><code>webView</code></td><td>blank</td><td>An empty blob.</td><td><code>#webViewSrc</code> pointing to an URL to render.</td></tr><tr><th>Code</th><td><code>code</code></td><td>Depends on the language (e.g. <code>text/plain</code>, <code>text/x-markdown</code>, <code>text/x-c++src</code>).</td><td>The plain text content.</td><td> </td></tr></tbody></table></figure>
|
||||
@@ -1,14 +0,0 @@
|
||||
# Options
|
||||
## Read an option
|
||||
|
||||
Add the import to the service (make sure the relative path is correct):
|
||||
|
||||
```javascript
|
||||
import options from "../../services/options.js";
|
||||
```
|
||||
|
||||
Them simply read the option:
|
||||
|
||||
```javascript
|
||||
this.firstDayOfWeek = options.getInt("firstDayOfWeek");
|
||||
```
|
||||
@@ -1,37 +0,0 @@
|
||||
# Check box option
|
||||
In the TPL:
|
||||
|
||||
```
|
||||
<div class="options-section">
|
||||
<h4>Background effects</h4>
|
||||
|
||||
<p>On the desktop application, it's possible to use a semi-transparent background tinted in the colors of the user's wallpaper to add a touch of color.</p>
|
||||
|
||||
<div class="col-6 side-checkbox">
|
||||
<label class="form-check">
|
||||
<input type="checkbox" class="background-effects form-check-input" />
|
||||
Enable background effects (Windows 11 only)
|
||||
</label>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
In `doRender()`:
|
||||
|
||||
```
|
||||
doRender() {
|
||||
this.$backgroundEffects = this.$widget.find("input.background-effects");
|
||||
|
||||
this.$backgroundEffects.on("change", () => this.updateCheckboxOption("backgroundEffects", this.$backgroundEffects));
|
||||
}
|
||||
```
|
||||
|
||||
In `optionsLoaded(options)`:
|
||||
|
||||
```
|
||||
async optionsLoaded(options) {
|
||||
|
||||
this.setCheckboxState(this.$backgroundEffects, options.backgroundEffects);
|
||||
|
||||
}
|
||||
```
|
||||
@@ -1,5 +0,0 @@
|
||||
# Creating a new option
|
||||
1. Go to `options_interface.ts` and add the option to `OptionDefinitions`, specifying its intended data type (boolean, string, number). Note that in the end the option will still be stored as a string, but this aids in type safety across the application.
|
||||
2. To add a new option with a set default, go to `options_init.ts` in the server and add a new entry in the `defaultOptions`.
|
||||
3. **Make the option adjustable by the client**
|
||||
By default options are not adjustable or visible to the client. To do so, modify `routes/api/options.ts` to add the newly added option to `ALLOWED_OPTIONS`.
|
||||
@@ -1,36 +0,0 @@
|
||||
# Displaying the option in settings
|
||||
Go to `src/public/app/widgets/type_widgets/options` and select a corresponding category, such as `appearance` and edit one of the JS files.
|
||||
|
||||
For example, to create a select:
|
||||
|
||||
First, modify the template (`TPL`), to add the new widget:
|
||||
|
||||
```
|
||||
<div class="col-6">
|
||||
<label>First day of the week</label>
|
||||
<select class="first-day-of-week-select form-control">
|
||||
<option value="0">Sunday</option>
|
||||
<option value="1">Monday</option>
|
||||
</select>
|
||||
</div>
|
||||
```
|
||||
|
||||
Secondly, create a reference to the new element in `doRender()`:
|
||||
|
||||
```
|
||||
this.$firstDayOfWeek = this.$widget.find(".first-day-of-week-select");
|
||||
```
|
||||
|
||||
Then in `optionsLoaded` adjust the value to the one set in the database:
|
||||
|
||||
```
|
||||
this.$firstDayOfWeek.val(options.firstDayOfWeek);
|
||||
```
|
||||
|
||||
To actually update the option, add a listener in `doRender`:
|
||||
|
||||
```
|
||||
this.$firstDayOfWeek.on("change", () => {
|
||||
this.updateOption("firstDayOfWeek", this.$firstDayOfWeek.val());
|
||||
});
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
# Refresh widget with option change
|
||||
To make a widget react to a change of a given option, simply add the following to the widget:
|
||||
|
||||
```javascript
|
||||
async entitiesReloadedEvent({loadResults}) {
|
||||
if (loadResults.getOptionNames().includes("firstDayOfWeek")) {
|
||||
// Do something.
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,12 +0,0 @@
|
||||
# Trigger UI refresh
|
||||
Call `utils.reloadFrontendApp`, but make sure to wait for the option to be saved first.
|
||||
|
||||
```
|
||||
this.$backgroundEffects.on("change", async () => {
|
||||
|
||||
await this.updateCheckboxOption("backgroundEffects", this.$backgroundEffects);
|
||||
|
||||
utils.reloadFrontendApp("background effect change");
|
||||
|
||||
});
|
||||
```
|
||||
@@ -1,15 +0,0 @@
|
||||
# Printing
|
||||
Note printing is handled by `note_detail.js`, in the `printActiveNoteEvent` method.
|
||||
|
||||
The application uses the [`print-this`](https://www.npmjs.com/package/print-this) library to isolate `.note-detail-printable:visible` and prepare it for printing.
|
||||
|
||||
Some scripts like KaTeX are manually injected in the footer, and the CSS to be used is manually defined. The most important one is `print.css`.
|
||||
|
||||
## Syntax highlighting
|
||||
|
||||
Syntax highlighting for code blocks is supported as well:
|
||||
|
||||
* It works by injecting a Highlight.js stylesheet into the print.
|
||||
* The theme used is hard-coded (the _Visual Studio Light theme_, at the time of writing) in order not to have a dark background in print.
|
||||
* The Highlight.js library is not needed since the `.note-detail-printable` which is rendered already has the `.hljs` classes added to it in order to achieve the syntax highlighting.
|
||||
* The user's choice of whether to enable syntax highlighting is also respected.
|
||||
@@ -1,6 +0,0 @@
|
||||
# Protected entities
|
||||
The following entities can be made protected, via their `isProtected` flag:
|
||||
|
||||
* <a class="reference-link" href="Database/attachments.md">attachments</a>
|
||||
* <a class="reference-link" href="Database/notes.md">notes</a>
|
||||
* <a class="reference-link" href="Database/revisions.md">revisions</a>
|
||||
@@ -1,11 +0,0 @@
|
||||
# Safe mode
|
||||
Safe mode is triggered by setting the `TRILIUM_SAFE_MODE` environment variable to a truthy value, usually `1`.
|
||||
|
||||
In each artifact there is a `trilium-safe-mode.sh` (or `.bat`) script to enable it.
|
||||
|
||||
What it does:
|
||||
|
||||
* Disables `customWidget` launcher types in `app/widgets/containers/launcher.js`.
|
||||
* Disables the running of `mobileStartup` or `frontendStartup` scripts.
|
||||
* Displays the root note instead of the previously saved session.
|
||||
* Disables the running of `backendStartup`, `hourly`, `daily` scripts and checks for the hidden subtree.
|
||||
@@ -1,17 +0,0 @@
|
||||
# Content hashing
|
||||
Entity hashing is done in `content_hash#getEntityHashes`.
|
||||
|
||||
* It works by looking at the `entity_changes` table and going through each of the entity names/types:
|
||||
* `blobs`
|
||||
* `attributes`
|
||||
* `revisions`
|
||||
* `attachments`
|
||||
* `notes`
|
||||
* `branches`
|
||||
* `etapi_tokens`
|
||||
* `options`
|
||||
* For some reason `note_reordering` entities are ignored specifically.
|
||||
* All the rows in `entity_changes` are then ordered alphabetically, based on their `entityId`.
|
||||
* Every entity row is then grouped by `entityName` and then by sector. The sector is defined as the first character of the `id`.
|
||||
* The hash is altered to add the `isErased` value as well since the hash of deleted entries is not updated.
|
||||
* For each sector, the hash is calculated using `utils.hash`, using SHA1 encoded as Base64.
|
||||
@@ -1,84 +0,0 @@
|
||||
# Syntax highlighting
|
||||
## Defining the MIME type
|
||||
|
||||
The first step to supporting a new language for either code blocks or code notes is to define the MIME type. Go to `mime_types.ts` and add a corresponding entry:
|
||||
|
||||
```
|
||||
{ title: "Batch file (DOS)", mime: "application/x-bat" }
|
||||
```
|
||||
|
||||
## Syntax highlighting for Highlight.js
|
||||
|
||||
### Built-in languages
|
||||
|
||||
Highlight.js supports a lot of languages out of the box, for some of them we just need to enable them by specifying one of the language aliases in the `highlightJs` field in the `mime_types` definition:
|
||||
|
||||
```
|
||||
{ title: "Batch file (DOS)", mime: "application/x-bat", highlightJs: "dos" }
|
||||
```
|
||||
|
||||
For the full list of supported languages, see [Supported Languages — highlight.js 11.9.0 documentation](https://highlightjs.readthedocs.io/en/latest/supported-languages.html). Look for the “Package” column to see if another library needs to be installed to support it.
|
||||
|
||||
Note that we are using the CDN build which may or may not have all the languages listed as predefined in the “Supported languages” list. To view the real list of supported files, see the `node_modules/@highlightjs/cdn-assets/languages` directory.
|
||||
|
||||
### Custom language
|
||||
|
||||
When the source code for a language is available, one way is to simply copy it to `libraries/highlightjs/{id}.js` where `id` matches the name for `highlightJs`.
|
||||
|
||||
Make sure in the script that the language is registered:
|
||||
|
||||
```
|
||||
hljs.registerLanguage('terraform', hljsDefineTerraform);
|
||||
```
|
||||
|
||||
Then in `mime_types.ts` make sure to set `highlightJsSource` to `libraries` to load it.
|
||||
|
||||
```
|
||||
{ title: "Terraform (HCL)", mime: "text/x-hcl", highlightJs: "terraform", highlightJsSource: "libraries", codeMirrorSource: "libraries/codemirror/hcl.js" },
|
||||
```
|
||||
|
||||
## Syntax highlighting for CodeMirror
|
||||
|
||||
### Custom language
|
||||
|
||||
Generally new languages are not added in the base installation and need to be separately registered. For CodeMirror 5 it seems that (at least for simple languages), the modes are distributed as _simple modes_ and can generally be copy-pasted in `libraries/codemirror`. An example would be:
|
||||
|
||||
```
|
||||
(() => {
|
||||
|
||||
CodeMirror.defineSimpleMode("batch", {
|
||||
|
||||
start: [],
|
||||
|
||||
echo: []
|
||||
|
||||
});
|
||||
|
||||
|
||||
|
||||
CodeMirror.defineMIME("application/x-bat", "batch");
|
||||
|
||||
CodeMirror.modeInfo.push({
|
||||
|
||||
ext: [ "bat", "cmd" ],
|
||||
|
||||
mime: "application/x-bat",
|
||||
|
||||
mode: "batch",
|
||||
|
||||
name: "Batch file"
|
||||
|
||||
});
|
||||
|
||||
})();
|
||||
|
||||
|
||||
```
|
||||
|
||||
Note that changing `modeInfo` is crucial, otherwise syntax highlighting will not work. The `mime` field is mandatory, even if `mimes` is used instead.
|
||||
|
||||
Afterwards, register it in `mime_types.ts`, specifying `codeMirrorSource` to point to the newly created file:
|
||||
|
||||
```
|
||||
{ title: "Batch file (DOS)", mime: "application/x-bat", highlightJs: "dos", codeMirrorSource: "libraries/codemirror/batch.js" }
|
||||
```
|
||||
@@ -1,17 +0,0 @@
|
||||
# Themes
|
||||
## Server-side
|
||||
|
||||
* There are three themes embedded in the application:
|
||||
* `light`, located in `src\public\stylesheets\theme-light.css`
|
||||
* `dark`, located in `src\public\stylesheets\theme-dark.css`
|
||||
* `next`, located in `src\public\stylesheets\theme-next.css`.
|
||||
* The default theme is set only once, when the database is created and is managed by `options_init#initNotSyncedOptions`.
|
||||
* In the original implementation: On Electron, the choice between `light` and `dark` is done based on the OS preference. Otherwise, the theme is always `dark`.
|
||||
* Now, we always choose `next` as the default theme.
|
||||
* The theme is served via `src\routes\index.ts`, in the `getThemeCssUrl` method.
|
||||
|
||||
## Client-side
|
||||
|
||||
* The predefined themes are hard-coded in the client in `src\public\app\widgets\type_widgets\options\appearance\theme.js`.
|
||||
* The user-defined themes are obtained via a call to the server: `options/user-themes`.
|
||||
* The theme retrieval is done via a request.
|
||||
Reference in New Issue
Block a user