docs(desktop): document deep-link URL schemes (#3373)

Author: bartlomieju

api_links_test.ts

@@ -9,6 +9,7 @@ const DIRS_TO_CHECK = ["./runtime"];
  * Matches: `Deno.serve`  `Deno.readFile()`  `Deno.FsFile`
  * Ignores: [`Deno.serve`](/api/deno/~/Deno.serve)  (already linked)
  * Ignores: references inside fenced code blocks
+ * Ignores: section headings (linking a heading breaks anchor nav, see #3358)
  */
 function findUnlinkedDenoApis(
   content: string,
@@ -26,6 +27,10 @@ function findUnlinkedDenoApis(
     }
     if (inCodeBlock) continue;
 
+    // Skip headings: linking a section heading to the API reference breaks the
+    // on-this-page anchor navigation (see issue #3358).
+    if (/^#{1,6}\s/.test(line)) continue;
+
     // Match `Deno.something` or `Deno.something()` NOT preceded by [
     const regex = /(?<!\[)`(Deno\.[a-zA-Z]\w+(?:\.\w+)*?)(?:\(\))?`/g;
     let match;

runtime/desktop/configuration.md

@@ -1,7 +1,7 @@
 ---
-last_modified: 2026-06-25
+last_modified: 2026-06-30
 title: "Configuration"
-description: "Configure deno desktop in deno.json: app metadata, icons, backend selection, output paths, error reporting, and the auto-update server."
+description: "Configure deno desktop in deno.json: app metadata, icons, deep-link URL schemes, backend selection, output paths, error reporting, and the auto-update server."
 ---
 
 :::info Available in Deno 2.9
@@ -21,6 +21,7 @@ still compiles, using sensible defaults.
 {
   "name": "my-app",
   "version": "1.4.0",
+  "exports": "./main.ts",
   "desktop": {
     "app": {
       "name": "My App",
@@ -29,7 +30,8 @@ still compiles, using sensible defaults.
         "macos": "./icons/app.icns",
         "windows": "./icons/app.ico",
         "linux": "./icons/app.png"
-      }
+      },
+      "deepLinks": ["myapp"]
     },
     "backend": "cef",
     "output": {
@@ -101,6 +103,52 @@ are assembled into the right container per platform.
 
 If no `icons` entry is set for a platform, the default Deno icon is used.
 
+### `app.deepLinks`
+
+Custom URL schemes (deep links) the app registers with the OS, so that opening a
+`<scheme>://...` link routes to your app. Each entry is a bare scheme name with
+no `://`.
+
+```jsonc
+"deepLinks": ["myapp"]
+```
+
+With the above, the OS treats `myapp://open/document/42` as belonging to your
+app. List several schemes if your app handles more than one:
+
+```jsonc
+"deepLinks": ["myapp", "myapp-beta"]
+```
+
+Scheme names follow the
+[RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-3.1) grammar:
+they must start with an ASCII letter and may otherwise contain letters, digits,
+`+`, `-`, and `.`. Names are lowercased during registration. The reserved
+schemes `http`, `https`, `file`, `ftp`, `ws`, and `wss` are rejected, since
+registering them as app handlers would hijack normal browsing. An invalid or
+reserved scheme fails the build.
+
+Registration happens at bundle time, per platform:
+
+- **macOS** adds a `CFBundleURLTypes` entry (with your schemes under
+  `CFBundleURLSchemes`) to the bundle `Info.plist`. This is written before
+  code-signing so the signature stays valid.
+- **Linux** adds an `x-scheme-handler/<scheme>` MIME type to the `.desktop`
+  entry and ensures `Exec=` forwards the opened URL via the `%u` field code.
+- **Windows** has no in-bundle registration for protocol handlers, so the
+  bundler drops a `register-deep-links.bat` next to the launcher. It writes the
+  `HKCU\Software\Classes\<scheme>` keys pointing back at the launcher. An
+  installer (or the user) runs it once after install.
+
+:::info Registration only
+
+This registers the schemes with the OS so links are routed to your app. Handling
+the opened URL inside a running app (delivering the URL to your code) is coming
+in a later release; declare your schemes now so packaging and OS registration
+are in place.
+
+:::
+
 ## `backend`
 
 Which web rendering engine to embed. One of `"cef"`, `"webview"`, or `"raw"`.
@@ -221,5 +269,6 @@ Configuration is validated at the start of `deno desktop`:
 - Icon paths must resolve to existing files.
 - Output paths must be writable.
 - `release.baseUrl` must parse as a URL.
+- `app.deepLinks` entries must be valid, non-reserved URL schemes.
 
 Errors are reported with the offending `deno.json` location.

runtime/desktop/tray_and_dock.md

@@ -1,5 +1,5 @@
 ---
-last_modified: 2026-06-25
+last_modified: 2026-06-30
 title: "Tray and dock"
 description: "Add icons to the OS status area and the macOS dock: tooltips, dark-mode variants, click events, and right-click context menus."
 ---
@@ -18,7 +18,7 @@ version, [update Deno](/runtime/reference/cli/upgrade/) to use it.
 
 Menus on both use the [`Deno.MenuItem`](/runtime/desktop/menus/) type.
 
-## [`Deno.Tray`](/api/deno/~/Deno.Tray)
+## `Deno.Tray`
 
 ```ts
 const icon = await Deno.readFile("./icons/tray.png");
@@ -210,7 +210,7 @@ If the backend cannot create a tray icon, the constructor's underlying `trayId`
 is `0` and subsequent calls are no-ops (silently). Check `tray.trayId !== 0` if
 you need to fall back gracefully.
 
-## [`Deno.dock`](/api/deno/~/Deno.dock)
+## `Deno.dock`
 
 [`Deno.dock`](/api/deno/~/Deno.dock) is a singleton exposing the app's dock /
 taskbar controls. The methods are cross-platform but their effect varies: