Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
feat(core): read-only virtual notes as a provider capability
Elian Doran0404a89a5976
diff --git a/apps/client/src/components/note_context.spec.ts b/apps/client/src/components/note_context.spec.tsindex f762b21ac2..94be608a47 100644--- a/apps/client/src/components/note_context.spec.ts+++ b/apps/client/src/components/note_context.spec.ts@@ -75,6 +75,19 @@ describe("NoteContext read-only capability", () => {if (noteContext.viewScope) noteContext.viewScope.readOnlyTemporarilyDisabled = true;expect(await noteContext.isReadOnly()).toBe(false);});++ it("keeps a note whose content cannot be saved read-only, even once editing is enabled", async () => {+ const note = buildNote({ title: "Help page", type: "text" });+ note.isContentWritable = false;+ noteContext.noteId = note.noteId;+ expect(await noteContext.isReadOnly()).toBe(true);++ noteContext.resetViewScope();+ const viewScope = noteContext.viewScope;+ expect(viewScope).toBeTruthy();+ if (viewScope) viewScope.readOnlyTemporarilyDisabled = true;+ expect(await noteContext.isReadOnly()).toBe(true);+ });});describe("NoteContext view scope", () => {diff --git a/apps/client/src/components/note_context.ts b/apps/client/src/components/note_context.tsindex 3f0d336841..e5ac166ada 100644--- a/apps/client/src/components/note_context.ts+++ b/apps/client/src/components/note_context.ts@@ -398,7 +398,7 @@ class NoteContext extends Component implements EventListener<"entitiesReloaded">/** @returns {Promise<boolean>} */async isReadOnly() {- if (this?.viewScope?.readOnlyTemporarilyDisabled) {+ if (this?.viewScope?.readOnlyTemporarilyDisabled && this.note?.isContentWritable !== false) {return false;}@@ -416,7 +416,7 @@ class NoteContext extends Component implements EventListener<"entitiesReloaded">return false;}- if (options.is("databaseReadonly")) {+ if (options.is("databaseReadonly") || !this.note.isContentWritable) {return true;}diff --git a/apps/client/src/components/root_command_executor.ts b/apps/client/src/components/root_command_executor.tsindex a8dc70c366..073ab1e6ab 100644--- a/apps/client/src/components/root_command_executor.ts+++ b/apps/client/src/components/root_command_executor.ts@@ -12,7 +12,7 @@ import Component from "./component.js";export default class RootCommandExecutor extends Component {editReadOnlyNoteCommand() {const noteContext = appContext.tabManager.getActiveContext();- if (noteContext?.viewScope) {+ if (noteContext?.viewScope && noteContext.note?.isContentWritable !== false) {noteContext.viewScope.readOnlyTemporarilyDisabled = true;appContext.triggerEvent("readOnlyTemporarilyDisabled", { noteContext });}diff --git a/apps/client/src/entities/fnote.ts b/apps/client/src/entities/fnote.tsindex 5a6279cdc9..0e01d37226 100644--- a/apps/client/src/entities/fnote.ts+++ b/apps/client/src/entities/fnote.ts@@ -34,6 +34,8 @@ export interface FNoteRow {type: NoteType;mime: string;blobId: string;+ /** Sent only as `false`, for a virtual note whose provider cannot save content. */+ isContentWritable?: boolean;}export interface NoteMetaData {@@ -59,6 +61,8 @@ export default class FNote {mime!: string;// the main use case to keep this is to detect content change which should trigger refreshblobId!: string;+ /** `false` for a note that no editing mode can unlock, such as a page of the in-app help. */+ isContentWritable!: boolean;attributes: string[];targetRelations: string[];@@ -104,6 +108,7 @@ export default class FNote {this.mime = row.mime ?? "";this.blobId = row.blobId;+ this.isContentWritable = row.isContentWritable ?? true;}addParent(parentNoteId: string, branchId: string, sort = true) {diff --git a/apps/client/src/translations/en/translation.json b/apps/client/src/translations/en/translation.jsonindex a395a7b3d8..33d2688d83 100644--- a/apps/client/src/translations/en/translation.json+++ b/apps/client/src/translations/en/translation.json@@ -3920,6 +3920,8 @@"read_only_explicit_description": "This note has been manually set to read-only.\nClick to edit it temporarily.","read_only_auto": "Auto read-only","read_only_auto_description": "This note was set automatically to read-only mode for performance reasons. This automatic limit is adjustable from settings.\n\nClick to edit it temporarily.",+ "read_only_locked": "Read-only",+ "read_only_locked_description": "This note is provided by Trilium and cannot be edited.","read_only_temporarily_disabled": "Temporarily editable","read_only_temporarily_disabled_description": "This note is currently editable, but it is normally read-only. The note will go back to being read-only as soon as you navigate to another note.\n\nClick to re-enable read-only mode.","office_preview": "Preview",diff --git a/apps/client/src/widgets/layout/NoteActions.tsx b/apps/client/src/widgets/layout/NoteActions.tsxindex e98e08dd8f..2e17a487c5 100644--- a/apps/client/src/widgets/layout/NoteActions.tsx+++ b/apps/client/src/widgets/layout/NoteActions.tsx@@ -91,7 +91,7 @@ export function NoteContextMenu({ note, noteContext, itemsAtStart, itemsNearNote&& !note.hasLabel("calendarRoot") && !note.hasLabel("workspaceCalendarRoot");const isHelpPage = note.noteId.startsWith("_help");const [syncServerHost] = useTriliumOption("syncServerHost");- const { isReadOnly, enableEditing } = useIsNoteReadOnly(note, noteContext);+ const { isReadOnly, isLocked, enableEditing } = useIsNoteReadOnly(note, noteContext);const isViewReadOnly = useEffectiveReadOnly(note, noteContext);// The views other than the board open their properties dialog only while they are editable.const hasCollectionProperties = isBoard@@ -123,7 +123,7 @@ export function NoteContextMenu({ note, noteContext, itemsAtStart, itemsNearNote{(note.type === "code" || note.noteId === "_backendLog") && <CodeProperties note={note} />}- {isReadOnly && <>+ {isReadOnly && !isLocked && <><CommandItem icon="bx bx-pencil" text={t("read-only-info.edit-note")}command={() => enableEditing()} /><FormDropdownDivider />diff --git a/apps/client/src/widgets/layout/NoteBadges.spec.tsx b/apps/client/src/widgets/layout/NoteBadges.spec.tsxindex 8fb871c20b..616983357c 100644--- a/apps/client/src/widgets/layout/NoteBadges.spec.tsx+++ b/apps/client/src/widgets/layout/NoteBadges.spec.tsx@@ -23,10 +23,23 @@ vi.mock("../../services/i18n", () => ({import { buildNote } from "../../test/easy-froca";import { renderInto } from "../../test/render";-import { ClippedNoteBadge, ExecuteBadge, OfficePreviewBadge } from "./NoteBadges";+import { ClippedNoteBadge, ExecuteBadge, OfficePreviewBadge, ReadOnlyBadge } from "./NoteBadges";const DOCX_MIME = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";+describe("ReadOnlyBadge", () => {+ it("says a note that cannot be saved is read-only, without offering to edit it", () => {+ const note = buildNote({ title: "Help page", type: "text" });+ note.isContentWritable = false;+ shownNote.current = note;+ shownNote.viewScope = { viewMode: "default" };++ const badge = renderInto(<ReadOnlyBadge />).querySelector(".read-only-badge");+ expect(badge).toBeTruthy();+ expect(badge?.textContent).toBe("breadcrumb_badges.read_only_locked");+ });+});+describe("OfficePreviewBadge", () => {it("marks a file note that the office preview renders", () => {const badge = renderBadge({ type: "file", mime: DOCX_MIME });diff --git a/apps/client/src/widgets/layout/NoteBadges.tsx b/apps/client/src/widgets/layout/NoteBadges.tsxindex f2e9783b22..95ca6f32f9 100644--- a/apps/client/src/widgets/layout/NoteBadges.tsx+++ b/apps/client/src/widgets/layout/NoteBadges.tsx@@ -43,12 +43,19 @@ export default function NoteBadges() {);}-function ReadOnlyBadge() {+export function ReadOnlyBadge() {const { note, noteContext } = useNoteContext();- const { isReadOnly, enableEditing, temporarilyEditable } = useIsNoteReadOnly(note, noteContext);+ const { isReadOnly, isLocked, enableEditing, temporarilyEditable } = useIsNoteReadOnly(note, noteContext);const isExplicitReadOnly = note?.isLabelTruthy("readOnly");- if (temporarilyEditable) {+ if (isLocked) {+ return <Badge+ icon="bx bx-lock-alt"+ text={t("breadcrumb_badges.read_only_locked")}+ tooltip={t("breadcrumb_badges.read_only_locked_description")}+ className="read-only-badge"+ />;+ } else if (temporarilyEditable) {return <Badgeicon="bx bx-lock-open-alt"text={t("breadcrumb_badges.read_only_temporarily_disabled")}diff --git a/apps/client/src/widgets/react/hooks.tsx b/apps/client/src/widgets/react/hooks.tsxindex e7e7b40008..b01963051f 100644--- a/apps/client/src/widgets/react/hooks.tsx+++ b/apps/client/src/widgets/react/hooks.tsx@@ -1928,21 +1928,23 @@ export function useGlobalShortcut(keyboardShortcut: string | null | undefined, h/*** Indicates that the current note is in read-only mode, while an editing mode is available,- * and provides a way to switch to editing mode.+ * and provides a way to switch to editing mode. `isLocked` marks a note that no editing mode can+ * unlock, as its content cannot be saved; `enableEditing` does nothing for it.*/export function useIsNoteReadOnly(note: FNote | null | undefined, noteContext: NoteContext | undefined) {const [ isReadOnly, setIsReadOnly ] = useState<boolean | undefined>(undefined);const [ readOnlyAttr ] = useNoteLabelBoolean(note, "readOnly");const [ autoReadOnlyDisabledAttr ] = useNoteLabelBoolean(note, "autoReadOnlyDisabled");const [ temporarilyEditable, setTemporarilyEditable ] = useState(false);+ const isLocked = note?.isContentWritable === false;const enableEditing = useCallback((enabled = true) => {- if (noteContext?.viewScope) {+ if (noteContext?.viewScope && !isLocked) {noteContext.viewScope.readOnlyTemporarilyDisabled = enabled;appContext.triggerEvent("readOnlyTemporarilyDisabled", {noteContext});setTemporarilyEditable(enabled);}- }, [noteContext]);+ }, [noteContext, isLocked]);useEffect(() => {if (note && noteContext) {@@ -1954,13 +1956,13 @@ export function useIsNoteReadOnly(note: FNote | null | undefined, noteContext: N}, [ note, noteContext, noteContext?.viewScope, readOnlyAttr, autoReadOnlyDisabledAttr ]);useTriliumEvent("readOnlyTemporarilyDisabled", ({noteContext: eventNoteContext}) => {- if (noteContext?.ntxId === eventNoteContext.ntxId) {+ if (noteContext?.ntxId === eventNoteContext.ntxId && !isLocked) {setIsReadOnly(!noteContext.viewScope?.readOnlyTemporarilyDisabled);setTemporarilyEditable(true);}});- return { isReadOnly, enableEditing, temporarilyEditable };+ return { isReadOnly, isLocked, enableEditing, temporarilyEditable };}/**diff --git a/apps/server/spec/in_app_help.spec.ts b/apps/server/spec/in_app_help.spec.tsindex 11bdf15317..40a6a24bc0 100644--- a/apps/server/spec/in_app_help.spec.ts+++ b/apps/server/spec/in_app_help.spec.ts@@ -119,7 +119,7 @@ describe("in-app help (shipped artifacts)", () => {it("makes every page read-only", () => {for (const item of flatten(meta)) {- expect(becca.getNoteOrThrow(item.id).isLabelTruthy("readOnly")).toBe(true);+ expect(becca.getNoteOrThrow(item.id).isContentWritable()).toBe(false);}});});diff --git a/apps/server/src/assets/help/help_content.json b/apps/server/src/assets/help/help_content.jsonindex 0a9a661469..3be0c0beab 100644--- a/apps/server/src/assets/help/help_content.json+++ b/apps/server/src/assets/help/help_content.json@@ -72,12 +72,12 @@"_help_vZWERwf8U3nx": "<figure class=\"image\"><img style=\"aspect-ratio:2089/1515;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/Note%20Revisions_image.png\" width=\"2089\" height=\"1515\"></figure><p>Trilium supports seamless versioning of notes by storing snapshots (\"revisions\") of notes at regular intervals.</p><p>To display the revisions, press the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> and select <em>Note revisions…</em> (<span class=\"tn-icon bx bx-history\"></span>).</p><h2>Interaction</h2><aside class=\"admonition note\"><p>This documentation matches the redesign of the note revisions dialog on v0.103.0, older versions have a similar dialog but with some differences.</p></aside><ul><li>The full list of revisions are displayed on the left in reverse chronological order.<ul><li>The revisions are grouped by the date the revision was taken.</li><li>This list does not contain the <em>current state</em> of the note, so it is possible to have notes with no revisions/snapshots saved.</li></ul></li><li>The icon of a revision indicates the <em>source</em> of that revision (e.g. a <span class=\"tn-icon bx bx-save\"></span> icon for a manually saved revision).</li><li>Pressing the <span class=\"tn-icon bx bx-dots-horizontal-rounded\"></span> button on the top-right of the dialog displays multiple options, including:<ul><li><span class=\"tn-icon bx bx-save\"></span> Saving a new revision now.</li><li>Checking the interval and limit for this note (see below).</li><li><span class=\"tn-icon bx bx-trash\"></span> Deleting all the revisions of this note.</li></ul></li><li>For supported notes (text, code), changes are highlighted. This behavior can be toggled via the <em>Highlight changes</em> at the top of the dialog.<ul><li>The highlighted changes are relative to the <strong>current state of the note</strong>, not to the revision prior to this one.</li></ul></li><li>For any given revision, the buttons on the top-right allow operating on it:<ul><li><span class=\"tn-icon bx bx-trash\"></span> Deleting the revision.</li><li><span class=\"tn-icon bx bx-download\"></span> Downloading the revision locally.</li><li><span class=\"tn-icon bx bx-history\"></span> Restoring the revision, which replaces the current content of the note with the one from the revision. Another revision is saved containing the current content of the note.</li></ul></li></ul><h2>Named revisions</h2><p>Named revisions are a new feature of Trilium v0.103.0 which allows adding a short description of what the changes in the snapshot contain.</p><p>In the list of note revisions:</p><ul><li>The name of the revision is displayed underneath the time of the revision in the sidebar, as well as at the top of the dialog where it is displayed in full.</li><li>Clicking on the <span class=\"tn-icon bx bx-edit-alt\"></span> edit button near the name of the revision allows it to be changed.</li></ul><p>To create a named revision, either:</p><ul><li>Go to the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a>, select <em>Save named revision…</em> (<span class=\"tn-icon bx bx-purchase-tag\"></span>), enter the name of revision and confirm.</li><li>Use the corresponding <a href=\"#root/_help_A9Oc6YKKc65v\">keyboard shortcut</a> or the <a class=\"reference-link\" href=\"#root/_help_F1r9QtzQLZqm\">Jump to & command palette</a> command with the same name.</li><li>Save a revision normally, and adjust the name afterwards from the note revision list.</li></ul><h2>When revisions are saved</h2><p>Revisions are saved:</p><ul><li>Automatically at a fixed interval. This behavior can be configured (see below).</li><li>Manually, by:<ul><li>Going to the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> and selecting <em>Save revision</em> (<span class=\"tn-icon bx bx-save\"></span>).</li><li>Using the <em>Force Save Revision</em> <a href=\"#root/_help_A9Oc6YKKc65v\">keyboard shortcut</a>.</li><li>In the <em>Note Revisions</em> dialog, pressing the <span class=\"tn-icon bx bx-dots-horizontal-rounded\"></span> button in the top-right and selecting <em>Save a revision now</em>.</li></ul></li></ul><p>Additionally, revisions can also come from somewhere else, and this is indicated via the icon of the revision:</p><ul><li><span class=\"tn-icon bx bx-code-alt\"></span> Generated externally, by <a class=\"reference-link\" href=\"#root/_help_pgxEVkzLl1OP\">ETAPI (REST API)</a>.</li><li><span class=\"tn-icon bx bx-bot\"></span> A modification created by <a class=\"reference-link\" href=\"#root/_help_GBBMSlVSOIGP\">AI</a>.</li><li><span class=\"tn-icon bx bx-history\"></span> A revision is restored, causing the existing note content to be saved as a revision to prevent potential data loss.</li></ul><h4>Snapshot interval</h4><p>Time interval of taking note snapshot is configurable in the Options → Other dialog. This provides a trade-off between more revisions and more data to store.</p><p>To turn off note versioning for a particular note (or sub-tree), add <code>disableVersioning</code> <a href=\"#root/_help_zEY4DaJG4YT5\">label</a> to the note.</p><h4>Maximum revisions</h4><p>The limit on the number of note snapshots can be configured in the Options → Other dialog. The note revision snapshot number limit refers to the maximum number of revisions that can be saved for each note. Where -1 means no limit, 0 means delete all revisions. You can set the maximum revisions for a single note through the <code>versioningLimit=X</code> label.</p><p>The note limit will not take effect immediately; it will only apply when the note is modified.</p><p>You can click the <em>Erase now</em> button under <em>Erase excess revision snapshots</em> to apply the changes immediately.</p>","_help_aGlEvb9hyDhS": "<h2>Manual sorting</h2><p>You can sort notes by right-clicking the parent note in the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> and selecting Advanced -> Sort notes by ... This will sort existing notes, but will not automatically sort future notes added to this parent note.</p><p>The sorting dialog allows:</p><ul><li>Sorting by title, creation or modification date, or by the value of a label on the child notes.</li><li>Sorting by several such criteria in turn, each ascending or descending: the next level only decides between notes the previous ones left equal.</li><li>Ensuring folders are displayed at the top.</li><li>Natural sort, based on the sorting rules of a particular language.</li></ul><h2>Automatic/Permanent Sorting</h2><p>Child notes can be automatically sorted by attaching specific <a href=\"#root/_help_zEY4DaJG4YT5\">labels</a> to the parent note:</p><figure class=\"table\"><table><thead><tr><th>Label</th><th>Description</th></tr></thead><tbody><tr><td><code>#sorted</code></td><td><p>Keeps child notes sorted by title alphabetically.</p><p>When given a value, it will sort by other criteria instead: a comma-separated list of levels, each <code>title</code>, <code>dateCreated</code>, <code>dateModified</code> or the name of a label on the child notes, optionally followed by <code>asc</code> or <code>desc</code>, as in a search's <code>orderBy</code>. For example <code>#sorted=\"priority desc, dueDate\"</code> sorts by priority, highest first, and notes of equal priority by due date. A child note without a level's label sorts after every child that has it, whichever direction the level runs in. When neither note has the label, the next level decides.</p></td></tr><tr><td><code>#sortDirection</code></td><td><p>If <code>sorted</code> is applied, specifies the direction of the sort:</p><ul><li><code>ASC</code>, ascending (default)</li><li><code>DESC</code>, descending</li></ul><p>A level of <code>sorted</code> followed by its own <code>asc</code> or <code>desc</code> keeps that direction regardless.</p></td></tr><tr><td><code>#sortFoldersFirst</code></td><td>If <code>sorted</code> is applied, folders (notes with children) will be sorted as a group at the top (at the bottom when <code>#sortDirection</code> is <code>desc</code>), and the rest will be sorted.</td></tr><tr><td><code>#sortNatural</code></td><td>Sort numbers naturally instead of alphabetically, so 2 comes before 10.</td></tr><tr><td><code>#sortLocale</code></td><td>The language code driving the natural sort (e.g. <code>zh-CN</code>, <code>de</code>). Only meaningful together with <code>#sortNatural</code>.</td></tr><tr><td><code>#top</code></td><td>If <code>sorted</code> is applied to the parent note, keeps given note on top in its parent.</td></tr><tr><td><code>#bottom</code></td><td>If <code>sorted</code> is applied to the parent note, keeps given note on bottom in its parent.</td></tr></tbody></table></figure><p>Sorting is done by comparing note properties or specific labels on child notes. There are four sorting levels, with the first having the highest priority. Lower priority levels are applied only if higher priority comparisons result in equality.</p><ol><li><strong>Top Label Sorting</strong>: Child notes with the <code>#top</code> label will appear at the top of the folder.</li><li><strong>Bottom Label Sorting</strong>: (Introduced in Trilium 0.62) Child notes with the <code>#bottom</code> label will appear at the bottom of the folder.</li><li><strong>Property/Label-Based Sorting</strong>: Sorting is based on the parent note's <code>#sorted</code> label:<ul><li><strong>Default Sorting</strong>: If <code>#sorted</code> has no value, notes are sorted alphabetically.</li><li><strong>Property Sorting</strong>: If <code>#sorted</code> is set to <code>title</code>, <code>dateModified</code>, or <code>dateCreated</code>, notes are sorted based on the specified property.</li><li><strong>Label Sorting</strong>: If <code>#sorted</code> has any other value, this value is treated as the name of a child note's label, and sorting is based on the values of this label. For example, setting <code>#sorted=myOrder</code> on the parent note and using <code>#myOrder=001</code>, <code>#myOrder=002</code>, etc., on child notes.</li><li><strong>Multi-Level Sorting</strong>: Several of the above can be combined, separated by commas; each level is applied only where the previous ones are equal. Every level can carry its own direction as a word after the name, <code>asc</code> or <code>desc</code>, otherwise it follows <code>#sortDirection</code>. For example <code>#sorted=\"priority desc, area, dateCreated\"</code> sorts by priority, highest first, then by area, then by creation date.</li></ul></li><li><strong>Alphabetical Sorting</strong>: Used as a last resort when other criteria result in equality.</li></ol><p>All comparisons are made string-wise (e.g., \"1\" < \"2\" or \"2020-10-10\" < \"2021-01-15\", but also \"2\" > \"10\").</p>","_help_NRnIZmSMc5sj": "<figure class=\"image\"><img style=\"aspect-ratio:2023/1488;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/Printing%20%26%20Exporting%20as%20PDF_image.png\" width=\"2023\" height=\"1488\"><figcaption>Screenshot of the Print preview functionality introduced in v0.103.0.</figcaption></figure><p>Trilium allows printing notes to a real printer, or generating a structured PDF for a single note or for multiple notes through <a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a>.</p><p>Note that not all note types are printable as of now. We do plan to increase the coverage of supported note types in the future.</p><p>Printing and exporting as PDF are not perfect. Due to technical limitations, and sometimes even browser or Electron glitches the text might appear cut off in some circumstances. </p><h2>Printing a note or exporting as PDF on the desktop</h2><aside class=\"admonition note\"><p>Versions prior to v0.103.0 had two different options, one for printing and another one for exporting to PDF. With the introduction of the print preview, these functions have been unified.</p></aside><p>On the desktop application of Trilium it is possible to export a note as PDF. To print a note:</p><ul><li>Press the menu button in the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> and select <em>Print note</em>.</li><li>Alternatively, printing can be triggered from a <a href=\"#root/_help_A9Oc6YKKc65v\">keyboard shortcut</a> (unassigned by default) or through the <a href=\"#root/_help_F1r9QtzQLZqm\">command palette</a>.</li></ul><p>This will trigger the print preview screen next.</p><h3>Print preview & print options</h3><p>The print preview dialog allows the following printing options to be adjusted:</p><ul><li>The printer to use<ul><li><em>Save as PDF</em> generates a PDF that is structured (maintains a table of contents, keeps the text selectable). Prefer this over other virtual PDF printers that ship with the operating system.</li></ul></li><li>Page orientation: <em>Portrait</em> (default) or <em>Landscape</em>.</li><li>Page size</li><li>Scale the entire content from 10% to 200% to improve the fit within the page.</li><li>Margins, which can be removed completely or adjusted individually for all the four edges.</li><li>Print only a subset of pages. Individual page numbers are separated by colons and hyphen-based ranges are supported (e.g. 3-5 for pages 3 to 5).</li></ul><p>Additional interaction:</p><ul><li><em>Print using system dialog</em> allows setting more options that are otherwise not available in Trilium.</li></ul><p>If the note cannot be rendered with the current options, or stops making progress for 30 seconds, the preview is replaced by an error message. Adjust the options to try again.</p><aside class=\"admonition note\"><p>Most of the options here (except printer & which pages to print) are managed at note level through <a class=\"reference-link\" href=\"#root/_help_zEY4DaJG4YT5\">Attributes</a> (such as <code>#printLandscape</code>, <code>#printPageSize</code>, <code>#printScale</code>, <code>#printMargins</code>).</p><p>This means that the print settings will be restored when printing the same note. There are no default settings that can be configured for all the notes, but this can be achieved via <a href=\"#root/_help_bwZpz2ajCEwO\">inheritable attributes</a>.</p></aside><h2>Printing on the browser</h2><p>This feature allows printing of notes. It works on both the desktop client, but also on the web.</p><p>To print a note, click the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> and select <em>Print note</em>. Depending on the size and type of the note, this can take up to a few seconds. Afterwards you will be redirected to the system/browser printing dialog.</p><p>On the server or PWA (mobile), the option is not available due to technical constraints and it will be hidden.</p><h2>Reporting issues with the rendering</h2><p>Should you encounter any visual issues in the resulting PDF file (e.g. a table does not fit properly, there is cut off text, etc.) feel free to <a href=\"#root/_help_wy8So3yZZlH9\">report the issue</a>. In this case, it's best to offer a sample note (click on the <span class=\"tn-icon cke cke-three-vertical-dots\"></span> button, select <em>Export note</em> → <em>This note and all of its descendants</em> → <em>HTML in ZIP archive</em>). Make sure not to accidentally leak any personal information.</p><p>Consider adjusting font sizes and using <a href=\"#root/_help_CohkqWQC1iBv\">page breaks</a> to work around the layout.</p><aside class=\"admonition tip\"><p>Although direct export as PDF is not available in the browser version of the application, it's still possible to generate a PDF by selecting the <em>Print</em> option instead and selecting “Save to PDF” as the printer (depending on the browser). Generally, Mozilla Firefox has better printing capabilities.</p></aside><h3>Automatic opening of the file</h3><p>When the PDF is exported, it is automatically opened with the system default application for easy preview.</p><p>Note that if you are using Linux with the GNOME desktop environment, sometimes the default application might seem incorrect (such as opening in GIMP). This is because it uses Gnome's “Recommended applications” list.</p><p>To solve this, you can change the recommended application for PDFs via this command line. First, list the available applications via <code>gio mime application/pdf</code> and then set the desired one. For example to use GNOME's Evince:</p><pre><code class=\"language-text-x-trilium-auto\">gio mime application/pdf</code></pre><h2>Printing multiple notes</h2><p>Since v0.100.0, it is possible to print more than one note at the time by using <a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a>:</p><ol><li>First create a collection.</li><li>Configure it to use <a class=\"reference-link\" href=\"#root/_help_mULW0Q3VojwY\">List View</a>.</li><li>Print the collection note normally.</li></ol><p>The resulting collection will contain all the children of the collection, while maintaining the hierarchy.</p><aside class=\"admonition note\"><p>Not all note types are supported when printing or exporting to PDF. When an unsupported note is encountered, it is skipped. At the end, if any of the notes were skipped, a message will be displayed with the possibility of viewing the full list of skipped notes. The same limitations as the ones described in <em>Constraints & limitations</em> apply.</p></aside><h2>Keyboard shortcut</h2><p>It's possible to trigger both printing and export as PDF from the keyboard by going to <em>Keyboard shortcuts</em> in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> and assigning a key combination for:</p><ul><li><em>Print Active Note</em></li><li><em>Export Active Note as PDF</em></li></ul><h2>Constraints & limitations</h2><p>Not all <a class=\"reference-link\" href=\"#root/_help_KSZ04uQ2D1St\">Note Types</a> are supported when printing, in which case the <em>Print</em> and <em>Export as PDF</em> options will be disabled.</p><ul><li>For <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes, font, background and table colors are printed in the shades of light themes, whatever the current theme (see <a class=\"reference-link\" href=\"#root/_help_Gr6xFaF6ioJ5\">General formatting</a>).</li><li>For <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> notes:<ul><li>Line numbers are not printed.</li><li>Syntax highlighting is enabled, however a default theme (Visual Studio) is enforced.</li></ul></li><li>A <a class=\"reference-link\" href=\"#root/_help_HcABDtFCkbFN\">Render Note</a> is printed as it is displayed, without running its script again, once its <code>~renderNote</code> relation is set.</li><li>For <a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a>, the following are supported:<ul><li><a class=\"reference-link\" href=\"#root/_help_mULW0Q3VojwY\">List View</a>, allowing to print multiple notes at once while preserving hierarchy (similar to a book).</li><li><a class=\"reference-link\" href=\"#root/_help_zP3PMqaG71Ct\">Presentation</a>, where each slide/sub-note is displayed.<ul><li>Most note types are supported, especially the ones that have an image representation such as <a class=\"reference-link\" href=\"#root/_help_grjYqerjn243\">Canvas</a> and <a class=\"reference-link\" href=\"#root/_help_gBbsAeiuUxI5\">Mind Map</a>.</li></ul></li><li><a class=\"reference-link\" href=\"#root/_help_2FvYrpmOXm29\">Table</a>, where the table is rendered in a print-friendly way.<ul><li>Tables that are too complex (especially if they have multiple columns) might not fit properly, however tables with a large number of rows are supported thanks to pagination.</li><li>Consider printing in landscape mode, or using <code>#printLandscape</code> if exporting to PDF.</li></ul></li><li>The rest of the collections are not supported, but we plan to add support for all the collection types at some point.</li></ul></li><li>Using <a class=\"reference-link\" href=\"#root/_help_AlhDUqhENtH7\">Custom app-wide CSS</a> for printing is no longer supported, instead a custom <code>printCss</code> relation needs to be used (see below).</li></ul><h2>Customizing the print CSS</h2><p>As an advanced use case, it's possible to customize the CSS used for printing such as adjusting the fonts, sizes or margins. Note that <a class=\"reference-link\" href=\"#root/_help_AlhDUqhENtH7\">Custom app-wide CSS</a> will not work for printing.</p><p>To do so:</p><ul><li>Create a CSS <a href=\"#root/_help_6f9hih2hXXZk\">code note</a>.</li><li>On the note being printed, apply the <code>~printCss</code> relation to point to the newly created CSS code note.</li><li>To apply the CSS to multiple notes, consider using <a href=\"#root/_help_bwZpz2ajCEwO\">inheritable attributes</a> or <a class=\"reference-link\" href=\"#root/_help_KC1HB96bqqHX\">Templates</a>.</li></ul><p>For example, to change the font of the document from the one defined by the theme or the user to a serif one:</p><pre><code class=\"language-text-x-trilium-auto\">body {\n\t--print-font-family: serif;\n --print-font-size: 11pt;\n}</code></pre><aside class=\"admonition important\"><p>When altering <code>--print-font-family</code>, make sure the change is done at <code>body</code> level and not <code>:root</code>, since otherwise it won't be picked up due to specificity rules.</p></aside><p>To remark:</p><ul><li>Multiple CSS notes can be add by using multiple <code>~printCss</code> relations.</li><li>If the note pointing to the <code>printCss</code> doesn't have the right note type or mime type, it will be ignored.</li><li>If migrating from a previous version where <a class=\"reference-link\" href=\"#root/_help_AlhDUqhENtH7\">Custom app-wide CSS</a>, there's no need for <code>@media print {</code> since the style-sheet is used only for printing.</li></ul><h2>Under the hood</h2><p>Both printing and exporting as PDF use the same mechanism: a note is rendered individually in a separate webpage that is then sent to the browser or the Electron application either for printing or exporting as PDF.</p><p>The webpage that renders a single note can actually be accessed in a web browser. For example <code>http://localhost:8080/#root/WWRGzqHUfRln/RRZsE9Al8AIZ?ntxId=0o4fzk</code> becomes <code>http://localhost:8080/?print#root/WWRGzqHUfRln/RRZsE9Al8AIZ</code>.</p><p>Accessing the print note in a web browser allows for easy debugging to understand why a particular note doesn't render well. The mechanism for rendering is similar to the one used in <a class=\"reference-link\" href=\"#root/_help_0ESUbbAxVnoK\">Note List</a>.</p>",- "_help_CoFPLs3dRlXc": "<p>Some note types such as <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a>, <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> notes and even some of the <a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a> can be set to read-only. When a note is in read-only mode, it is presented to the user in a non-editable view, with the option to switch to editing mode if needed.</p><h2>Automatic read-only mode</h2><p>For optimization purposes, Trilium will automatically set very large notes to read-only. Displaying such lengthy notes in editing mode can slow down performance, especially when editing is unnecessary.</p><p>This behavior can be disabled on a per-note basis, by following the instructions of the next section.</p><p>In addition, it's possible to change the number of characters at which the automatic read-only mode will trigger in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> by going to the options for <a class=\"reference-link\" href=\"#root/_hidden/_options/_optionsTextNotes\">Text Notes</a> and <a class=\"reference-link\" href=\"#root/_hidden/_options/_optionsCodeNotes\">Code Notes</a>.</p><h2>Changing a note's read-only behavior</h2><p>A note's read-only behavior can be changed via <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> → <em>Editable.</em> The following options are possible:</p><ul><li><strong>Auto</strong><br>This is the default behavior in which the note will be editable by default, unless it becomes large enough to trigger read-only mode.</li><li><strong>Read-only</strong><br>The note will be always marked as read-only, regardless of its size. Nevertheless, it's still possible to temporarily edit the note if needed. This is generally useful for notes that are not prone to change.</li><li><strong>Always Editable</strong><br>This option will bypass the automatic read-only activation for this particular note. It's useful for large notes that are frequently edited.</li></ul><p>If the <em>Editable</em> section is missing from the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a>, then the note type does not support read-only mode.</p><h3>Manually setting the options</h3><p>Apart from using the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> as previously mentioned, it's also possible to use <a href=\"#root/_help_zEY4DaJG4YT5\">labels</a> to change the behavior:</p><ul><li>To set as read-only, apply the <code>readOnly</code> label to the note.</li><li>To disable automatic read-only (always editable), apply the <code>autoReadOnlyDisabled</code> label.</li></ul><h2>Temporarily editing a read-only note</h2><p>When accessing a read-only note, it's possible to temporarily edit it pressing the <em>Read-only</em> badge.</p><p>When pressed, the note will become editable but will become read-only again after navigating to a different note.</p>",+ "_help_CoFPLs3dRlXc": "<p>Some note types such as <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a>, <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> notes and even some of the <a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a> can be set to read-only. When a note is in read-only mode, it is presented to the user in a non-editable view, with the option to switch to editing mode if needed.</p><h2>Automatic read-only mode</h2><p>For optimization purposes, Trilium will automatically set very large notes to read-only. Displaying such lengthy notes in editing mode can slow down performance, especially when editing is unnecessary.</p><p>This behavior can be disabled on a per-note basis, by following the instructions of the next section.</p><p>In addition, it's possible to change the number of characters at which the automatic read-only mode will trigger in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> by going to the options for <a class=\"reference-link\" href=\"#root/_hidden/_options/_optionsTextNotes\">Text Notes</a> and <a class=\"reference-link\" href=\"#root/_hidden/_options/_optionsCodeNotes\">Code Notes</a>.</p><h2>Changing a note's read-only behavior</h2><p>A note's read-only behavior can be changed via <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> → <em>Editable.</em> The following options are possible:</p><ul><li><strong>Auto</strong><br>This is the default behavior in which the note will be editable by default, unless it becomes large enough to trigger read-only mode.</li><li><strong>Read-only</strong><br>The note will be always marked as read-only, regardless of its size. Nevertheless, it's still possible to temporarily edit the note if needed. This is generally useful for notes that are not prone to change.</li><li><strong>Always Editable</strong><br>This option will bypass the automatic read-only activation for this particular note. It's useful for large notes that are frequently edited.</li></ul><p>If the <em>Editable</em> section is missing from the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a>, then the note type does not support read-only mode.</p><h3>Manually setting the options</h3><p>Apart from using the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> as previously mentioned, it's also possible to use <a href=\"#root/_help_zEY4DaJG4YT5\">labels</a> to change the behavior:</p><ul><li>To set as read-only, apply the <code>readOnly</code> label to the note.</li><li>To disable automatic read-only (always editable), apply the <code>autoReadOnlyDisabled</code> label.</li></ul><h2>Temporarily editing a read-only note</h2><p>When accessing a read-only note, it's possible to temporarily edit it pressing the <em>Read-only</em> badge.</p><p>When pressed, the note will become editable but will become read-only again after navigating to a different note.</p><p>The pages of the built-in user guide are an exception: they are part of Trilium itself and cannot be edited, not even temporarily. Their <em>Read-only</em> badge cannot be pressed, and the note menu does not offer to edit them.</p>","_help_0ESUbbAxVnoK": "<figure class=\"image\"><img style=\"aspect-ratio:990/590;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/Note%20List_image.png\" width=\"990\" height=\"590\"></figure><p>When a note has one or more child notes, they will be listed at the end of the note for easy navigation.</p><h2>Configuration</h2><ul><li>To hide the note list for a particular note, simply apply the <code>hideChildrenOverview</code> <a href=\"#root/_help_zEY4DaJG4YT5\">label</a>.</li><li>For some view types, such as Grid view, only a subset of notes will be displayed and pagination can be used to navigate through all of them for performance reasons. To adjust the number of notes per page, set <code>pageSize</code> to the desired number.</li></ul><h2>View types</h2><p>The view types dictate how the child notes are represented. By default, the notes will be displayed in a grid, however there are also some other view types available.</p><p>Generally the view type can only be changed from the <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a>, but it can also be changed manually on any type of note using the <code>#viewType</code> <a href=\"#root/_help_HI6GBBIduIgv\">label</a>.</p>","_help_S0Fos78ZfcY7": "<p>The inbox is the default destination for quickly captured notes. When a note is created without picking a location first, it lands in the inbox. This makes it easy to quickly capture notes and sort them later.</p><h2>Where the inbox is used</h2><ul><li>The <em>New note</em> button in the <a class=\"reference-link\" href=\"#root/_help_xYmIYSP6wE3F\">Launch Bar</a>.</li><li>The global <em>Create note into inbox</em> shortcut (default <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>P</kbd>).</li><li>The <em>New note</em> action in the <a href=\"#root/_help_7iwde4lsKc6O\">tray icon menu</a>.</li><li>The <a class=\"reference-link\" href=\"#root/_help_MtPxeAWVAzMg\">Web Clipper</a> extension.</li><li>The <em>Create note</em> option offered when a search finds no match, in <a class=\"reference-link\" href=\"#root/_help_F1r9QtzQLZqm\">Jump to & command palette</a>, in an empty tab and in the <code>@</code> completion of a text note.</li></ul><h2>Setting a note inbox</h2><p>To create a note inbox, apply the <code>#inbox</code> <a href=\"#root/_help_HI6GBBIduIgv\">label</a> to it.</p><p>Only one note should carry this label. If there are multiple notes, only one will be used by the application.</p><aside class=\"admonition note\"><p>If there is no inbox note, Trilium will fall back to today's <a href=\"#root/_help_l0tKav7yLHGF\">day note</a>, creating it and its calendar ancestors as needed. If the journal has been removed altogether, the note is created at the top level instead of a new journal being built for it.</p></aside><h2>Workspace inboxes</h2><p>Each <a href=\"#root/_help_9sRHySam5fXb\">workspace</a> can have its own inbox, set via the <code>#workspaceInbox</code> label.</p><p>When a new note is created while hoisted in a workspace, the location is determined in the following order:</p><ul><li>A note carrying the <code>#workspaceInbox</code> label in that workspace.</li><li>A note carrying the <code>#inbox</code> within that workspace.</li><li>Today's <a href=\"#root/_help_l0tKav7yLHGF\">day note</a>, if the workspace has a <code>#workspaceCalendarRoot</code>.</li><li>The workspace root note itself.</li></ul>","_help_5Ct4MAJTS4tQ": "<p>Deleted notes are listed in the <em>Deleted Notes</em> dialog (<a class=\"reference-link\" href=\"#root/_help_x3i7MxGccDuM\">Global menu</a> → <em>Show Deleted Notes</em>) and can be restored by pressing the <em>undelete</em> link.</p><p>If a note has child notes, they will be restored along with it. Should the original location no longer exist (e.g. the parent has been deleted), the note will be restored into the default location for new notes (<a class=\"reference-link\" href=\"#root/_help_S0Fos78ZfcY7\">Note Inbox</a>).</p><aside class=\"admonition note\"><p>When a note is hoisted in the tree, the dialog will only display notes deleted from the subtree of that hoisted note.</p></aside><p>To permanently erase deleted notes and clear the list, press the three-dots menu and select <em>Erase deleted notes now</em>.</p><p>Deleted notes are permanently erased after a certain amount of time (7 days by default). To change this interval, press the three-dots menu and select <em>Deleted Notes Settings</em>.</p>","_help_m3VlURMSeOrd": "<p>When an empty <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note is created, a note type switcher will appear below the inline <a class=\"reference-link\" href=\"#root/_help_l7pigIGu01K2\">Title</a>. Apart from changing the note type, it's also possible to apply a <a href=\"#root/_help_KC1HB96bqqHX\">template</a>:</p><ul><li><span class=\"tn-icon bx bxl-markdown\"></span> <em>Markdown</em> and <span class=\"tn-icon bx bx-pen\"></span> <em>Canvas</em> switch the note to that type in one click.</li><li><span class=\"tn-icon bx bx-code\"></span> <em>Code</em> lists the scripting notes (<em>Custom CSS</em>, <em>Widget</em> and <em>Backend script</em>), then the enabled code languages.</li><li><span class=\"tn-icon bx bx-book\"></span> <em>Collection</em> and <span class=\"tn-icon bx bx-copy-alt\"></span><em>Template</em> list the collections and the templates.</li><li><span class=\"tn-icon bx bx-dots-vertical-rounded\"></span> <em>All types</em> displays the same menu as <em>Insert note after</em> in the <a class=\"reference-link\" href=\"#root/_help_YtSN43OrfzaA\">Note tree contextual menu</a>, with every note type and template.</li></ul><p>Typing while the <span class=\"tn-icon bx bx-code\"></span> <em>Code</em>, <span class=\"tn-icon bx bx-copy-alt\"></span> <em>Template</em> or <span class=\"tn-icon bx bx-dots-vertical-rounded\"></span> <em>All types</em> menu is open narrows it down to the matching entries.</p><p>The switcher will disappear as soon as a text is entered.</p><img src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/New%20note%20type%20switcher_image.png\" width=\"735\" height=\"143\">",- "_help_B5dihXRDksTk": "<p>Note badges appear near the fixed note title and indicate important information about the note such as whether it is read-only. Some of the badges are also interactive.</p><figure class=\"image\"><img style=\"aspect-ratio:910/49;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/Note%20badges_image.png\" width=\"910\" height=\"49\"></figure><p>The following badges are available:</p><ul><li><span class=\"tn-icon bx bx-lock-alt\"></span> <strong>Read-only badge</strong>, which will be shown if the note is not editable due to either automatic read-only or manual read-only. Clicking on the badge will temporarily edit the note.</li><li><span class=\"tn-icon bx bx-share-alt\"></span> <strong>Share badge</strong>, which will indicate that the current note is shared. The badge will also indicate if the share is on the local network (for the desktop application without <a class=\"reference-link\" href=\"#root/_help_cbkrhQjrkKrh\">Synchronization</a> set up) or publicly accessible (for the server).</li><li><span class=\"tn-icon bx bx-globe\"></span> <strong>Web clip badge</strong>, which will indicate if the note was clipped using the <a class=\"reference-link\" href=\"#root/_help_MtPxeAWVAzMg\">Web Clipper</a>. The badge acts as a link, so it can be clicked on to navigate to the page or right clicked for more options. When the clipper also saved the page's description, its author, or the dates it was published and last updated, clicking the badge shows these details instead, with a link to the page at the top.</li><li><span class=\"tn-icon bx bx-play\"></span> <strong>Execute badge</strong>, for <a href=\"#root/_help_CdNpE2pqjmI6\">scripts</a> or <a href=\"#root/_help_YKWqdJhzi2VY\">saved SQL queries</a> which have an execute button or a description.</li><li>For <a class=\"reference-link\" href=\"#root/_help_YzMcWlCVeW09\">Active content</a> (e.g. scripts, styles), a dedicated badge will be shown indicating the type of note and with an option to easily enable or disable it.</li></ul>",+ "_help_B5dihXRDksTk": "<p>Note badges appear near the fixed note title and indicate important information about the note such as whether it is read-only. Some of the badges are also interactive.</p><figure class=\"image\"><img style=\"aspect-ratio:910/49;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/Note%20badges_image.png\" width=\"910\" height=\"49\"></figure><p>The following badges are available:</p><ul><li><span class=\"tn-icon bx bx-lock-alt\"></span> <strong>Read-only badge</strong>, which will be shown if the note is not editable due to either automatic read-only or manual read-only. Clicking on the badge will temporarily edit the note. On the pages of the built-in user guide, which cannot be edited, the badge does nothing when clicked.</li><li><span class=\"tn-icon bx bx-share-alt\"></span> <strong>Share badge</strong>, which will indicate that the current note is shared. The badge will also indicate if the share is on the local network (for the desktop application without <a class=\"reference-link\" href=\"#root/_help_cbkrhQjrkKrh\">Synchronization</a> set up) or publicly accessible (for the server).</li><li><span class=\"tn-icon bx bx-globe\"></span> <strong>Web clip badge</strong>, which will indicate if the note was clipped using the <a class=\"reference-link\" href=\"#root/_help_MtPxeAWVAzMg\">Web Clipper</a>. The badge acts as a link, so it can be clicked on to navigate to the page or right clicked for more options. When the clipper also saved the page's description, its author, or the dates it was published and last updated, clicking the badge shows these details instead, with a link to the page at the top.</li><li><span class=\"tn-icon bx bx-play\"></span> <strong>Execute badge</strong>, for <a href=\"#root/_help_CdNpE2pqjmI6\">scripts</a> or <a href=\"#root/_help_YKWqdJhzi2VY\">saved SQL queries</a> which have an execute button or a description.</li><li>For <a class=\"reference-link\" href=\"#root/_help_YzMcWlCVeW09\">Active content</a> (e.g. scripts, styles), a dedicated badge will be shown indicating the type of note and with an option to easily enable or disable it.</li></ul>","_help_Bsm4fyzPJkSc": "<p><img class=\"image-style-align-right\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/Save%20status%20indicator_image.png\" width=\"168\" height=\"47\">To the right of the note title, a temporary indicator appears after making a change to the document which shows whether the document has been saved.</p><p>It indicates the following states:</p><ul><li><span class=\"tn-icon bx bx-pencil\"></span> <em>Unsaved</em>, if the changes will be saved soon.</li><li><span class=\"tn-icon bx bx-loader\"></span> <em>Saving</em>, if the changes are being saved.</li><li><span class=\"tn-icon bx bx-check\"></span> <em>Saved</em>, if all the changes were successfully saved to the server.</li><li><span class=\"tn-icon bx bx-error\"></span> <em>Error</em>, if the changes could not be saved, for example due to a communication server with the server.</li></ul><p>After all changes have been saved, the indicator will hide automatically after a few seconds.</p>","_help_kBrnXNG3Hplm": "<p>This page explains the basic concepts related to the tree structure of notes in TriliumNext.</p><h2>Note</h2><p>A note is the central entity in TriliumNext. For more details, see <a class=\"reference-link\" href=\"#root/_help_BFs8mudNFgCS\">Notes</a>.</p><h2>Branch</h2><p>A branch describes the placement of a note within the note tree. Essentially, it is a tuple of <code>parentNoteId</code> and <code>noteId</code>, indicating that the given note is placed as a child under the specified parent note.</p><p>Each note can have multiple branches, meaning any note can be placed in multiple locations within the tree. This concept is referred to as <a class=\"reference-link\" href=\"#root/_help_IakOLONlIfGI\">Cloning Notes</a>.</p><h2>Prefix</h2><p>A prefix is a branch-specific title modifier for a note. If you place your note in two different locations within the tree and want to alter the title slightly in one of those placements, you can use a prefix.</p><p>To edit a prefix, right-click on the note in the tree pane and select <em>Edit branch prefix</em>.</p><p>The prefix is not part of the note itself and is not encrypted when the note is protected. This can be useful if you want part of the title to remain visible in the tree for easier navigation, even when the note is protected.</p><h2>Subtree</h2><p>A subtree consists of a particular note (the subtree root) and all its children and descendants. Some operations, such as exporting, work on entire subtrees.</p>","_help_MMiBEQljMQh2": "<p>One of the Trilium's goals is to provide fast and comfortable navigation between notes.</p><h2>Backwards and forward</h2><p>You can use alt-left and alt-right to move back and forward in history of viewed pages.</p><p>This works identically to browser backwards / forwards, it's actually using built-in browser support for this.</p><p><img src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Navigation/Note%20Navigation_image.jpg\"></p><h2>Jump to note</h2><p>This is useful to quickly find and view arbitrary notes - click on <code>Jump to</code> button on the top or press <kbd>Ctrl</kbd> + <kbd>J</kbd> . Then type part of the note name and autocomplete will help you pick the desired note.</p><p>See <a class=\"reference-link\" href=\"#root/_help_F1r9QtzQLZqm\">Jump to Note</a> for more information.</p>",diff --git a/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Note badges.md b/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Note badges.mdindex fc7fb41db6..0fb6a6d7ba 100644--- a/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Note badges.md+++ b/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Note badges.md@@ -5,7 +5,7 @@ Note badges appear near the fixed note title and indicate important informationThe following badges are available:-* <span class="tn-icon bx bx-lock-alt"></span> **Read-only badge**, which will be shown if the note is not editable due to either automatic read-only or manual read-only. Clicking on the badge will temporarily edit the note.+* <span class="tn-icon bx bx-lock-alt"></span> **Read-only badge**, which will be shown if the note is not editable due to either automatic read-only or manual read-only. Clicking on the badge will temporarily edit the note. On the pages of the built-in user guide, which cannot be edited, the badge does nothing when clicked.* <span class="tn-icon bx bx-share-alt"></span> **Share badge**, which will indicate that the current note is shared. The badge will also indicate if the share is on the local network (for the desktop application without <a class="reference-link" href="../../Installation%20%26%20Setup/Synchronization.md">Synchronization</a> set up) or publicly accessible (for the server).* <span class="tn-icon bx bx-globe"></span> **Web clip badge**, which will indicate if the note was clipped using the <a class="reference-link" href="../../Installation%20%26%20Setup/Web%20Clipper.md">Web Clipper</a>. The badge acts as a link, so it can be clicked on to navigate to the page or right clicked for more options. When the clipper also saved the page's description, its author, or the dates it was published and last updated, clicking the badge shows these details instead, with a link to the page at the top.* <span class="tn-icon bx bx-play"></span> **Execute badge**, for [scripts](../../Scripting.md) or [saved SQL queries](../../Advanced%20Usage/Database/Manually%20altering%20the%20database/SQL%20Console.md) which have an execute button or a description.diff --git a/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Read-Only Notes.md b/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Read-Only Notes.mdindex 69f7c7c814..6222526d58 100644--- a/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Read-Only Notes.md+++ b/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Read-Only Notes.md@@ -33,4 +33,6 @@ Apart from using the <a class="reference-link" href="../UI%20Elements/Note%20meWhen accessing a read-only note, it's possible to temporarily edit it pressing the _Read-only_ badge.-When pressed, the note will become editable but will become read-only again after navigating to a different note.\ No newline at end of file+When pressed, the note will become editable but will become read-only again after navigating to a different note.++The pages of the built-in user guide are an exception: they are part of Trilium itself and cannot be edited, not even temporarily. Their _Read-only_ badge cannot be pressed, and the note menu does not offer to edit them.\ No newline at end of filediff --git a/packages/trilium-core/src/becca/entities/abstract_becca_entity.ts b/packages/trilium-core/src/becca/entities/abstract_becca_entity.tsindex 5852f3fa07..c472d27955 100644--- a/packages/trilium-core/src/becca/entities/abstract_becca_entity.ts+++ b/packages/trilium-core/src/becca/entities/abstract_becca_entity.ts@@ -1,3 +1,4 @@+import { ValidationError } from "../../errors.js";import eventService from "../../services/events";import blobService from "../../services/blob.js";@@ -36,18 +37,18 @@ abstract class AbstractBeccaEntity<T extends AbstractBeccaEntity<T>> {/*** Virtual entities exist only in becca — they are injected by a virtual note provider* (see `services/virtual_notes.ts`), never persisted to the database and never synced.- * They are read-only: {@link save}, {@link markAsDeleted} and content updates throw.+ * {@link save} and {@link markAsDeleted} throw; content goes through the note's provider.*/isVirtual?: boolean;- /** @throws Error when this entity is virtual — virtual entities must never touch the database. */+ /** @throws ValidationError when this entity is virtual, since virtual entities never touch the database. */protected ensureNotVirtual(action: string) {if (!this.isVirtual) {return;}const constructorData = this.constructor as unknown as ConstructorData<T>;- throw new Error(`Cannot ${action} ${constructorData.entityName} '${(this as any)[constructorData.primaryKeyName]}': it is a virtual entity (provided by a virtual note provider) and is read-only.`);+ throw new ValidationError(`Cannot ${action} ${constructorData.entityName} '${(this as any)[constructorData.primaryKeyName]}': it is a virtual entity (provided by a virtual note provider) and is read-only.`);}protected beforeSaving(opts?: {}) {diff --git a/packages/trilium-core/src/becca/entities/battachment.ts b/packages/trilium-core/src/becca/entities/battachment.tsindex f29f556b66..9ad9f2bea3 100644--- a/packages/trilium-core/src/becca/entities/battachment.ts+++ b/packages/trilium-core/src/becca/entities/battachment.ts@@ -2,6 +2,7 @@import { type AttachmentRow, isImageAttachmentRole } from "@triliumnext/commons";+import { ValidationError } from "../../errors.js";import dateUtils from "../../services/utils/date";import { getLog } from "../../services/log.js";import noteService from "../../services/notes.js";@@ -237,6 +238,10 @@ class BAttachment extends AbstractBeccaEntity<BAttachment> {}override beforeSaving() {+ if (this.becca.notes[this.ownerId]?.isVirtual) {+ throw new ValidationError(`Cannot save an attachment of note '${this.ownerId}': virtual notes have no attachments.`);+ }+super.beforeSaving();if (this.position === undefined || this.position === null) {diff --git a/packages/trilium-core/src/becca/entities/bnote.ts b/packages/trilium-core/src/becca/entities/bnote.tsindex 5b3b39b18d..c9f4cfe27e 100644--- a/packages/trilium-core/src/becca/entities/bnote.ts+++ b/packages/trilium-core/src/becca/entities/bnote.ts@@ -21,7 +21,7 @@ import BRevision from "./brevision.js";import { getLog } from "../../services/log.js";import { getSql } from "../../services/sql/index.js";import { formatDownloadTitle, isStringNote, normalize, randomString, replaceAll } from "../../services/utils/index.js";-import { getVirtualNoteContent } from "../../services/virtual_notes.js";+import { getVirtualNoteContent, isVirtualNoteContentWritable, setVirtualNoteContent } from "../../services/virtual_notes.js";const LABEL = "label";const RELATION = "relation";@@ -251,11 +251,21 @@ class BNote extends AbstractBeccaEntity<BNote> {}setContent(content: Uint8Array | string, opts: ContentOpts = {}) {+ if (this.isVirtual) {+ setVirtualNoteContent(this.noteId, content);+ return;+ }+this._setContent(content, opts);eventService.emit(eventService.NOTE_CONTENT_CHANGE, { entity: this });}+ /** Whether the content can be saved: always for a persisted note, per provider for a virtual one. */+ isContentWritable() {+ return !this.isVirtual || isVirtualNoteContentWritable(this.noteId);+ }+setJsonContent(content: {}) {this.setContent(JSON.stringify(content, null, "\t"));}diff --git a/packages/trilium-core/src/becca/entities/brevision.ts b/packages/trilium-core/src/becca/entities/brevision.tsindex f7f94bf51d..d4b45e9a75 100644--- a/packages/trilium-core/src/becca/entities/brevision.ts+++ b/packages/trilium-core/src/becca/entities/brevision.ts@@ -1,5 +1,6 @@"use strict";+import { ValidationError } from "../../errors.js";import protectedSessionService from "../../services/protected_session.js";import dateUtils from "../../services/utils/date";import becca from "../becca.js";@@ -184,6 +185,10 @@ class BRevision extends AbstractBeccaEntity<BRevision> {}override beforeSaving() {+ if (this.becca.notes[this.noteId]?.isVirtual) {+ throw new ValidationError(`Cannot save a revision of note '${this.noteId}': virtual notes have no revisions.`);+ }+super.beforeSaving();this.utcDateModified = dateUtils.utcNowDateTime();diff --git a/packages/trilium-core/src/becca/virtual_notes_injection.spec.ts b/packages/trilium-core/src/becca/virtual_notes_injection.spec.tsindex 9292f68f06..d45c606c85 100644--- a/packages/trilium-core/src/becca/virtual_notes_injection.spec.ts+++ b/packages/trilium-core/src/becca/virtual_notes_injection.spec.ts@@ -1,5 +1,6 @@import { afterAll, beforeAll, describe, expect, it } from "vitest";+import { ValidationError } from "../errors.js";import { getContext } from "../services/context.js";import noteService from "../services/notes.js";import { getSql } from "../services/sql/index.js";@@ -116,9 +117,16 @@ describe("virtual note injection", () => {it("virtual entities are read-only", () => {const note = becca.getNoteOrThrow("_vtestPage");- expect(() => getContext().init(() => note.save())).toThrow(/read-only/);- expect(() => getContext().init(() => note.setContent("<p>nope</p>"))).toThrow(/read-only/);- expect(() => getContext().init(() => note.markAsDeleted())).toThrow(/read-only/);+ expect(note.isContentWritable()).toBe(false);+ expect(() => getContext().init(() => note.save())).toThrow(ValidationError);+ expect(() => getContext().init(() => note.setContent("<p>nope</p>"))).toThrow(ValidationError);+ expect(() => getContext().init(() => note.markAsDeleted())).toThrow(ValidationError);+ expect(() => getContext().init(() => note.saveRevision())).toThrow(ValidationError);+ expect(() => getContext().init(() => note.saveAttachment({+ role: "file", mime: "text/plain", title: "notes.txt", content: "nope"+ }))).toThrow(ValidationError);+ expect(countRows("revisions", "noteId")).toBe(0);+ expect(countRows("attachments", "ownerId")).toBe(0);const branch = becca.getBranch("_hidden__vtest");expect(branch).toBeTruthy();@@ -128,6 +136,31 @@ describe("virtual note injection", () => {expect(() => getContext().init(() => attribute.save())).toThrow(/read-only/);});+ it("hands content to a provider that can save it, keeping it out of the database", () => {+ const saved = new Map<string, string | Uint8Array>();+ registerVirtualNoteProvider({+ namespace: "_vtw",+ parentNoteId: "_hidden",+ getSubtree: () => [{ id: "_vtwFile", title: "File", type: "text" }],+ getContent: (noteId) => saved.get(noteId),+ setContent: (noteId, content) => { saved.set(noteId, content); }+ });++ try {+ reloadBecca();+ const note = becca.getNoteOrThrow("_vtwFile");+ expect(note.isContentWritable()).toBe(true);++ getContext().init(() => note.setContent("<p>saved</p>"));+ expect(note.getContent()).toBe("<p>saved</p>");+ expect(getSql().getValue("SELECT COUNT(*) FROM entity_changes WHERE entityId LIKE '\\_vtw%' ESCAPE '\\'")).toBe(0);+ expect(getSql().getValue("SELECT COUNT(*) FROM notes WHERE noteId LIKE '\\_vtw%' ESCAPE '\\'")).toBe(0);+ } finally {+ unregisterVirtualNoteProvider("_vtw");+ reloadBecca();+ }+ });+it("rejects persisting branches or attributes that reference virtual notes", () => {const realNote = getContext().init(() =>noteService.createNewNote({diff --git a/packages/trilium-core/src/routes/api/notes.spec.ts b/packages/trilium-core/src/routes/api/notes.spec.tsindex 0bfa3ac838..1422d23cc3 100644--- a/packages/trilium-core/src/routes/api/notes.spec.ts+++ b/packages/trilium-core/src/routes/api/notes.spec.ts@@ -1,9 +1,12 @@-import { beforeAll, describe, expect, it, vi } from "vitest";+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";import becca from "../../becca/becca";+import { load } from "../../becca/becca_loader";+import { getContext } from "../../services/context";import eraseService from "../../services/erase";import noteService from "../../services/notes";import { getSql } from "../../services/sql/index";+import { registerVirtualNoteProvider, unregisterVirtualNoteProvider } from "../../services/virtual_notes";import ws from "../../services/ws";import { createTextNote } from "../../test/api_fixtures";import { CoreApiTester } from "../../test/api_tester";@@ -745,4 +748,27 @@ describe("Notes API (core)", () => {expect(res.body.noteIdsToBeDeleted).toEqual([]);});});++ describe("read-only virtual notes", () => {+ beforeAll(() => {+ registerVirtualNoteProvider({+ namespace: "_vapi",+ parentNoteId: "_hidden",+ getSubtree: () => [{ id: "_vapiPage", title: "Page", type: "text" }],+ getContent: () => "<p>shipped</p>"+ });+ getContext().init(() => load());+ });++ afterAll(() => {+ unregisterVirtualNoteProvider("_vapi");+ getContext().init(() => load());+ });++ it("refuses content and revision writes as a client error", async () => {+ expect((await api.put("/api/notes/_vapiPage/data", { body: { content: "<p>edited</p>" } })).status).toBe(400);+ expect((await api.post("/api/notes/_vapiPage/revision")).status).toBe(400);+ expect(becca.getNoteOrThrow("_vapiPage").getContent()).toBe("<p>shipped</p>");+ });+ });});diff --git a/packages/trilium-core/src/routes/api/tree.spec.ts b/packages/trilium-core/src/routes/api/tree.spec.tsindex 9c33b754fa..65e95892d9 100644--- a/packages/trilium-core/src/routes/api/tree.spec.ts+++ b/packages/trilium-core/src/routes/api/tree.spec.ts@@ -1,6 +1,9 @@import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";import becca from "../../becca/becca";+import { load } from "../../becca/becca_loader";+import { getContext } from "../../services/context";+import { registerVirtualNoteProvider, unregisterVirtualNoteProvider } from "../../services/virtual_notes";import { createTextNote } from "../../test/api_fixtures";import { CoreApiTester } from "../../test/api_tester";@@ -53,6 +56,30 @@ describe("Tree API (core)", () => {expect(res.body.notes.some((n) => n.noteId === "root")).toBe(true);});+ it("marks a note whose content cannot be saved, and only that note", async () => {+ registerVirtualNoteProvider({+ namespace: "_vtree",+ parentNoteId: "_hidden",+ getSubtree: () => [{ id: "_vtreePage", title: "Page", type: "text" }],+ getContent: () => "<p>shipped</p>"+ });+ getContext().init(() => load());++ try {+ const res = await api.post<{ notes: { noteId: string; isContentWritable?: boolean }[] }>("/api/tree/load", {+ body: { noteIds: [ "root", "_vtreePage" ] }+ });+ const byId = new Map(res.body.notes.map((note) => [ note.noteId, note ]));+ expect(byId.get("_vtreePage")?.isContentWritable).toBe(false);+ const root = byId.get("root");+ expect(root).toBeTruthy();+ expect(Object.hasOwn(root ?? {}, "isContentWritable")).toBe(false);+ } finally {+ unregisterVirtualNoteProvider("_vtree");+ getContext().init(() => load());+ }+ });+describe("edge cases", () => {afterEach(() => {vi.restoreAllMocks();diff --git a/packages/trilium-core/src/routes/api/tree.ts b/packages/trilium-core/src/routes/api/tree.tsindex b3fbecc1fe..1dc7f9bbe3 100644--- a/packages/trilium-core/src/routes/api/tree.ts+++ b/packages/trilium-core/src/routes/api/tree.ts@@ -53,7 +53,7 @@ function getNotesAndBranchesAndAttributes(_noteIds: string[] | Set<string>) {collectEntityIds(note);}- const notes: NoteRow[] = [];+ const notes: (NoteRow & { isContentWritable?: false })[] = [];for (const noteId of collectedNoteIds) {const note = becca.notes[noteId];@@ -64,7 +64,8 @@ function getNotesAndBranchesAndAttributes(_noteIds: string[] | Set<string>) {isProtected: note.isProtected,type: note.type,mime: note.mime,- blobId: note.blobId+ blobId: note.blobId,+ ...(note.isContentWritable() ? {} : { isContentWritable: false })});}diff --git a/packages/trilium-core/src/services/in_app_help.spec.ts b/packages/trilium-core/src/services/in_app_help.spec.tsindex 5d9557574e..29bb8356cb 100644--- a/packages/trilium-core/src/services/in_app_help.spec.ts+++ b/packages/trilium-core/src/services/in_app_help.spec.ts@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";import { EMPTY_BLOB_ID, type HelpBundle, type HiddenSubtreeItem } from "@triliumnext/commons";import becca from "../becca/becca.js";import { load } from "../becca/becca_loader.js";+import { ValidationError } from "../errors.js";import blobService from "./blob.js";import { getContext } from "./context.js";import { getHelpHiddenSubtreeData, HELP_ASSET_TOKEN, InAppHelpProvider, initInAppHelp } from "./in_app_help.js";@@ -138,14 +139,15 @@ describe("in_app_help", () => {expect(provider.readAssets).toEqual([ "User Guide/My pic.png" ]);});- it("makes every help page read-only through an inheritable label on the root", () => {+ it("makes every help page read-only, with no label the user could remove", () => {initInAppHelp(new TestHelpProvider([{ id: "_helpPage", title: "Page", type: "text" }]));reloadBecca();- // Owned by the root, inherited by the pages: the guide is never edited in place, and the- // application must not offer an editor for it.- expect(becca.getNoteOrThrow("_help").getOwnedAttribute("label", "readOnly")).toBeTruthy();- expect(becca.getNoteOrThrow("_helpPage").isLabelTruthy("readOnly")).toBe(true);+ const page = becca.getNoteOrThrow("_helpPage");+ expect(becca.getNoteOrThrow("_help").isContentWritable()).toBe(false);+ expect(page.isContentWritable()).toBe(false);+ expect(page.hasLabel("readOnly")).toBe(false);+ expect(() => getContext().init(() => page.setContent("<p>edited</p>"))).toThrow(ValidationError);});it("unregisters the help provider when none is supplied", () => {diff --git a/packages/trilium-core/src/services/in_app_help.ts b/packages/trilium-core/src/services/in_app_help.tsindex e0906f7d9c..c1e5f9cc10 100644--- a/packages/trilium-core/src/services/in_app_help.ts+++ b/packages/trilium-core/src/services/in_app_help.ts@@ -74,12 +74,6 @@ export function initInAppHelp(p: InAppHelpProvider) {type: "book",icon: "bx-help-circle",isExpanded: true,- // Inherited by every page: the guide is application-owned, so it opens in the- // reading view rather than an editor. Writes are refused by the entity layer- // anyway; this keeps the application from offering them in the first place.- attributes: [- { type: "label", name: "readOnly", value: "", isInheritable: true }- ],// HiddenSubtreeItem is structurally a VirtualSubtreeItem (its enforce*// fields are simply ignored here).children: getHelpHiddenSubtreeData()diff --git a/packages/trilium-core/src/services/virtual_notes.ts b/packages/trilium-core/src/services/virtual_notes.tsindex 94c964797d..0dbf3f14e1 100644--- a/packages/trilium-core/src/services/virtual_notes.ts+++ b/packages/trilium-core/src/services/virtual_notes.ts@@ -1,5 +1,7 @@import type { NoteType } from "@triliumnext/commons";+import { ValidationError } from "../errors.js";+/*** Virtual notes are notes that exist only in becca (and, through it, in the client's froca) —* they are never persisted to the database and never produce entity changes, so they are@@ -54,6 +56,12 @@ export interface VirtualNoteProvider {* them as attachments of the note, so the exported copy works without the provider.*/getAssets?(noteId: string): VirtualNoteAsset[];++ /**+ * Saves new content of a virtual note. Without it, the provider's notes are read-only. The+ * write stays on this instance, since virtual notes never sync.+ */+ setContent?(noteId: string, content: string | Uint8Array): void;}export interface VirtualNoteAsset {@@ -140,6 +148,21 @@ export function getVirtualNoteContent(noteId: string): string | Uint8Array {return getVirtualNoteProvider(noteId)?.getContent?.(noteId) ?? "";}+/** Whether the provider of a virtual note can save its content. */+export function isVirtualNoteContentWritable(noteId: string) {+ return !!getVirtualNoteProvider(noteId)?.setContent;+}++/** @throws ValidationError when the note's provider cannot save content. */+export function setVirtualNoteContent(noteId: string, content: string | Uint8Array) {+ const provider = getVirtualNoteProvider(noteId);+ if (!provider?.setContent) {+ throw new ValidationError(`Note '${noteId}' is read-only.`);+ }++ provider.setContent(noteId, content);+}+/** Assets of a virtual note, delegated to its provider; empty when the provider has none. */export function getVirtualNoteAssets(noteId: string): VirtualNoteAsset[] {return getVirtualNoteProvider(noteId)?.getAssets?.(noteId) ?? [];