feat: register trilium:// custom protocol handler for deep linking

apps/client/src/components/app_context.ts

@@ -173,6 +173,7 @@ export type CommandMappings = {
     collapseSubtree: ContextMenuCommandData;
     sortChildNotes: ContextMenuCommandData;
     copyNotePathToClipboard: ContextMenuCommandData;
+    copyNoteUrlToClipboard: ContextMenuCommandData;
     recentChangesInSubtree: ContextMenuCommandData;
     cutNotesToClipboard: ContextMenuCommandData;
     copyNotesToClipboard: ContextMenuCommandData;

apps/client/src/menus/tree_context_menu.ts

@@ -175,6 +175,7 @@ export default class TreeContextMenu implements SelectMenuItemEventListener<Tree
                     { kind: "separator" },
 
                     { title: t("tree-context-menu.copy-note-path-to-clipboard"), command: "copyNotePathToClipboard", uiIcon: "bx bx-directions", enabled: true },
+                    { title: t("tree-context-menu.copy-note-url-to-clipboard"), command: "copyNoteUrlToClipboard", uiIcon: "bx bx-link", enabled: true },
                     { title: t("tree-context-menu.recent-changes-in-subtree"), command: "recentChangesInSubtree", uiIcon: "bx bx-history", enabled: noSelectedNotes && notOptionsOrHelp }
                 ].filter(Boolean) as MenuItem<TreeCommandNames>[]
             },
@@ -350,6 +351,8 @@ export default class TreeContextMenu implements SelectMenuItemEventListener<Tree
             toastService.showMessage(t("tree-context-menu.converted-to-attachments", { count: converted }));
         } else if (command === "copyNotePathToClipboard") {
             navigator.clipboard.writeText(`#${  notePath}`);
+        } else if (command === "copyNoteUrlToClipboard") {
+            navigator.clipboard.writeText(`trilium://note/${this.node.data.noteId}`);
         } else if (command) {
             this.treeWidget.triggerCommand<TreeCommandNames>(command, {
                 node: this.node,

apps/client/src/translations/en/translation.json

@@ -1552,6 +1552,7 @@
     "recent-changes-in-subtree": "Recent changes in subtree",
     "convert-to-attachment": "Convert to attachment",
     "copy-note-path-to-clipboard": "Copy note path to clipboard",
+    "copy-note-url-to-clipboard": "Copy note URL to clipboard",
     "protect-subtree": "Protect subtree",
     "unprotect-subtree": "Unprotect subtree",
     "copy-clone": "Copy / clone",

apps/client/src/widgets/layout/Breadcrumb.tsx

@@ -438,6 +438,17 @@ function buildEmptyAreaContextMenu(parentComponent: Component | null, notePath:
                     uiIcon: "bx bx-directions",
                     handler: () => copyTextWithToast(`#${notePath}`)
                 },
+                {
+                    title: t("tree-context-menu.copy-note-url-to-clipboard"),
+                    command: "copyNoteUrlToClipboard",
+                    uiIcon: "bx bx-link",
+                    handler: () => {
+                        const noteId = notePath?.split("/").pop();
+                        if (noteId) {
+                            copyTextWithToast(`trilium://note/${noteId}`);
+                        }
+                    }
+                },
             ],
             x: e.pageX,
             y: e.pageY,

apps/desktop/src/main.ts

@@ -12,6 +12,7 @@ import { PRODUCT_NAME } from "./app-info";
 import port from "@triliumnext/server/src/services/port.js";
 import { join } from "path";
 import { deferred, LOCALES } from "../../../packages/commons/src";
+import protocolHandler from "./protocol-handler.js";
 
 async function main() {
     const userDataPath = getUserData();
@@ -24,6 +25,11 @@ async function main() {
         process.exit(0);
     }
 
+    // Register trilium:// as a custom URI scheme so external apps and the OS
+    // can launch Trilium and navigate directly to a note.
+    // Must be called before app.requestSingleInstanceLock().
+    app.setAsDefaultProtocolClient(protocolHandler.PROTOCOL);
+
     // Adds debug features like hotkeys for triggering dev tools and reload
     electronDebug();
     electronDl({ saveAs: true });
@@ -63,13 +69,41 @@ async function main() {
         await serverInitializedPromise;
         console.log("Starting Electron...");
         await onReady();
+
+        // Process protocol URL from first-launch argv (Windows/Linux only;
+        // macOS delivers protocol URLs via the open-url event).
+        if (process.platform !== "darwin") {
+            const noteId = protocolHandler.extractNoteIdFromArgs(process.argv);
+            if (noteId) {
+                protocolHandler.navigateToNote(noteId);
+            }
+        }
+
+        // Handle protocol URL that arrived via open-url before the window was
+        // ready (macOS cold-start from a trilium:// link).
+        protocolHandler.processPendingNavigation();
     });
 
     app.on("will-quit", () => {
         globalShortcut.unregisterAll();
     });
 
+    // macOS delivers protocol URLs for a *running* instance via open-url
+    // instead of second-instance.  When the app is cold-started from a
+    // trilium:// link the event fires before "ready", so we queue the note ID.
+    app.on("open-url", (event, url) => {
+        event.preventDefault();
+        protocolHandler.handleProtocolUrl(url);
+    });
+
     app.on("second-instance", (event, commandLine) => {
+        // Check for a trilium:// URL or --open-note flag first.
+        const noteId = protocolHandler.extractNoteIdFromArgs(commandLine);
+        if (noteId) {
+            protocolHandler.navigateToNote(noteId);
+            return;
+        }
+
         const lastFocusedWindow = windowService.getLastFocusedWindow();
         if (commandLine.includes("--new-window")) {
             windowService.createExtraWindow("");

apps/desktop/src/protocol-handler.ts

@@ -0,0 +1,123 @@
+import windowService from "@triliumnext/server/src/services/window.js";
+
+const PROTOCOL = "trilium";
+
+/** Note ID to navigate to once the main window finishes loading. */
+let pendingNoteId: string | null = null;
+
+/**
+ * Parses a `trilium://` URL and returns the note ID, or `null` if the URL
+ * cannot be parsed.
+ *
+ * Supported formats:
+ *   trilium://note/<noteId>   (canonical)
+ *   trilium://<noteId>        (shorthand)
+ */
+function parseTriliumUrl(rawUrl: string): string | null {
+    let parsed: URL;
+    try {
+        parsed = new URL(rawUrl);
+    } catch {
+        return null;
+    }
+
+    if (parsed.protocol !== `${PROTOCOL}:`) {
+        return null;
+    }
+
+    // trilium://note/<noteId> → hostname = "note", pathname = "/<noteId>"
+    if (parsed.hostname === "note") {
+        const noteId = parsed.pathname.replace(/^\/+/, "").trim();
+        return noteId || null;
+    }
+
+    // trilium://<noteId> → hostname = "<noteId>"
+    const noteId = parsed.hostname.trim();
+    return noteId || null;
+}
+
+/**
+ * Scans process arguments for a `trilium://` URL or `--open-note=<noteId>`
+ * flag and returns the target note ID.
+ */
+function extractNoteIdFromArgs(args: string[]): string | null {
+    for (const arg of args) {
+        if (arg.startsWith(`${PROTOCOL}://`)) {
+            return parseTriliumUrl(arg);
+        }
+
+        const match = arg.match(/^--open-note=(.+)$/);
+        if (match) {
+            return match[1].trim() || null;
+        }
+    }
+    return null;
+}
+
+/**
+ * Focuses the appropriate window and sends navigation IPC to the renderer.
+ * Waits for `did-finish-load` if the page is still loading (first launch).
+ *
+ * Returns `false` when no usable window exists yet.
+ */
+function navigateToNote(noteId: string): boolean {
+    const win =
+        windowService.getLastFocusedWindow() ?? windowService.getMainWindow();
+    if (!win || win.isDestroyed()) {
+        return false;
+    }
+
+    if (win.isMinimized()) {
+        win.restore();
+    }
+    win.show();
+    win.focus();
+
+    if (win.webContents.isLoading()) {
+        win.webContents.once("did-finish-load", () => {
+            win.webContents.send("openInSameTab", noteId);
+        });
+    } else {
+        win.webContents.send("openInSameTab", noteId);
+    }
+
+    return true;
+}
+
+/**
+ * Handles an incoming protocol URL (from `open-url`, `second-instance`, or
+ * first-launch argv).  If the main window is not yet available the note ID is
+ * queued for {@link processPendingNavigation}.
+ */
+function handleProtocolUrl(url: string): void {
+    const noteId = parseTriliumUrl(url);
+    if (!noteId) {
+        return;
+    }
+
+    if (!navigateToNote(noteId)) {
+        // Window not created yet — defer until after onReady().
+        pendingNoteId = noteId;
+    }
+}
+
+/**
+ * Navigates to the note that was requested before the window was ready, then
+ * clears the pending state.  Safe to call when there is nothing pending.
+ */
+function processPendingNavigation(): void {
+    if (pendingNoteId) {
+        const noteId = pendingNoteId;
+        pendingNoteId = null;
+        navigateToNote(noteId);
+    }
+}
+
+export default {
+    PROTOCOL,
+    parseTriliumUrl,
+    extractNoteIdFromArgs,
+    navigateToNote,
+    handleProtocolUrl,
+    processPendingNavigation,
+};