feat(docs): add self-referential deep links from docs to app screens

jamesarich · Copilot · jamesarich · commit 150fe62f93c4 · 2026-05-13T17:24:12.000-05:00
- Add deepLink field to DocPage and KeywordIndexEntry models
- Populate deep links for 7 user guide pages (connections, messages,
  nodes, map, settings, modules, firmware)
- DocsLinkUriHandler now intercepts meshtastic:// URIs in markdown
- DocsPageRouteScreen shows 'Open in App' button when deepLink is set
- DocsNavigation wires onDeepLink through platform UriHandler
- Add deep_link frontmatter field to 7 user doc pages
- Update navigation-and-deep-links developer doc with full reference
- Fix link validator to skip meshtastic:// URIs

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/docs/developer/navigation-and-deep-links.md b/docs/developer/navigation-and-deep-links.md
@@ -54,14 +54,19 @@ meshtastic://meshtastic/{path}
 
 | URI Path | Route | Notes |
 |----------|-------|-------|
+| `/connections` | `ConnectionsRoute.ConnectionsGraph` | Connections screen |
 | `/settings` | `SettingsRoute.SettingsGraph(null)` | Settings root |
+| `/settings/module-config` | `SettingsRoute.ModuleConfiguration` | Module config |
 | `/settings/helpDocs` | `SettingsRoute.HelpDocs` | Docs browser |
 | `/settings/helpDocs/{pageId}` | `SettingsRoute.HelpDocPage(pageId)` | Specific doc page |
 | `/settings/help-docs` | `SettingsRoute.HelpDocs` | Compatibility alias |
-| `/nodes` | `NodesRoute.Nodes` | Node list |
+| `/nodes` | `NodesRoute.NodesGraph` | Node list |
 | `/nodes/{destNum}` | `NodesRoute.NodeDetail(destNum)` | Node detail |
+| `/messages` | `ContactsRoute.ContactsGraph` | Conversation list |
 | `/messages/{contactKey}` | `ContactsRoute.Messages(contactKey)` | Conversation |
 | `/map` | `MapRoute.Map(null)` | Map view |
+| `/firmware` | `FirmwareRoute.FirmwareGraph` | Firmware screen |
+| `/channels` | `ChannelsRoute.ChannelsGraph` | Channel editor |
 
 ### Backstack Synthesis
 
@@ -117,5 +122,46 @@ fun `help docs deep link routes correctly`() {
 }
 ```
 
+## Self-Referential Deep Links in Docs
+
+User guide documentation pages can include a `deep_link` frontmatter field that maps the doc page to its corresponding app screen. When present, the in-app docs viewer shows an **"Open in App"** button in the top bar, allowing users to jump directly from documentation to the live feature.
+
+### How It Works
+
+1. The `deep_link` field in frontmatter specifies the target `meshtastic://` URI.
+2. `DocBundleLoader` populates `DocPage.deepLink` from the page definition.
+3. `DocsPageRouteScreen` renders a `TextButton` in the top app bar when `deepLink` is non-null.
+4. Tapping the button fires the URI through the platform `UriHandler`, which routes back through `UIViewModel.handleDeepLink()` → `DeepLinkRouter`.
+
+### Pages with Deep Links
+
+| Doc Page | Deep Link | Target Screen |
+|----------|-----------|---------------|
+| Connections | `meshtastic://meshtastic/connections` | Connections |
+| Messages & Channels | `meshtastic://meshtastic/messages` | Conversations |
+| Nodes | `meshtastic://meshtastic/nodes` | Node list |
+| Map & Waypoints | `meshtastic://meshtastic/map` | Map |
+| Settings — Radio & User | `meshtastic://meshtastic/settings` | Settings root |
+| Settings — Modules & Admin | `meshtastic://meshtastic/settings/module-config` | Module config |
+| Firmware Updates | `meshtastic://meshtastic/firmware` | Firmware |
+
+### Adding a Deep Link to a Doc Page
+
+1. Add `deep_link: meshtastic://meshtastic/{path}` to the page's YAML frontmatter.
+2. Add the matching `deepLink` parameter to the page's `UserPageDef` in `DocBundleLoader`.
+3. The in-app docs viewer picks up the deep link automatically — no further UI changes needed.
+
+> **Note:** Deep links in frontmatter are ignored by Jekyll and Docusaurus, ensuring no broken links on external doc sites. The `meshtastic://` URI scheme is only active in-app.
+
+### Inline Deep Links in Markdown
+
+The `DocsLinkUriHandler` also intercepts `meshtastic://` URIs in markdown content. Authors can use inline deep links for contextual "try it now" actions:
+
+```markdown
+Configure your LoRa preset in [Settings](meshtastic://meshtastic/settings/lora).
+```
+
+These links only work in the in-app docs viewer. On Jekyll/Docusaurus, they render as non-functional links. Use sparingly and always provide equivalent text instructions.
+
 ---
 
diff --git a/docs/user/connections.md b/docs/user/connections.md
@@ -3,6 +3,7 @@ title: Connections
 nav_order: 2
 last_updated: 2026-05-13
 description: Connect your phone or desktop to a Meshtastic radio via Bluetooth, USB, or TCP/IP.
+deep_link: meshtastic://meshtastic/connections
 aliases:
   - bluetooth
   - usb
diff --git a/docs/user/firmware.md b/docs/user/firmware.md
@@ -3,6 +3,7 @@ title: Firmware Updates
 nav_order: 13
 last_updated: 2026-05-13
 description: Update your radio firmware over Bluetooth — OTA process, version channels, pre-flight checks, and recovery.
+deep_link: meshtastic://meshtastic/firmware
 aliases:
   - firmware
   - update
diff --git a/docs/user/map-and-waypoints.md b/docs/user/map-and-waypoints.md
@@ -3,6 +3,7 @@ title: Map & Waypoints
 nav_order: 6
 last_updated: 2026-05-13
 description: View node positions on the map, create and share waypoints, and manage position sharing and privacy.
+deep_link: meshtastic://meshtastic/map
 aliases:
   - map
   - waypoints
diff --git a/docs/user/messages-and-channels.md b/docs/user/messages-and-channels.md
@@ -3,6 +3,7 @@ title: Messages & Channels
 nav_order: 3
 last_updated: 2026-05-13
 description: Send and receive messages, manage channels, configure encryption, and use quick chat, reactions, and message actions.
+deep_link: meshtastic://meshtastic/messages
 aliases:
   - channels
   - direct-messages
diff --git a/docs/user/nodes.md b/docs/user/nodes.md
@@ -3,6 +3,7 @@ title: Nodes
 nav_order: 4
 last_updated: 2026-05-13
 description: Browse, filter, and sort mesh nodes — view details, signal quality, roles, and quick actions.
+deep_link: meshtastic://meshtastic/nodes
 aliases:
   - node-list
   - mesh-nodes
diff --git a/docs/user/settings-module-admin.md b/docs/user/settings-module-admin.md
@@ -3,6 +3,7 @@ title: Settings — Modules & Admin
 nav_order: 8
 last_updated: 2026-05-13
 description: Configure optional feature modules (MQTT, telemetry, canned messages, TAK, and more) and perform device administration.
+deep_link: meshtastic://meshtastic/settings/module-config
 aliases:
   - modules
   - module-config
diff --git a/docs/user/settings-radio-user.md b/docs/user/settings-radio-user.md
@@ -3,6 +3,7 @@ title: Settings — Radio & User
 nav_order: 7
 last_updated: 2026-05-13
 description: Configure your radio hardware, LoRa presets, user profile, position sharing, power management, and security.
+deep_link: meshtastic://meshtastic/settings
 aliases:
   - settings
   - radio-config
diff --git a/feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/data/DocBundleLoader.kt b/feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/data/DocBundleLoader.kt
@@ -156,6 +156,7 @@ class DefaultDocBundleLoader : DocBundleLoader {
         val aliases: List<String>,
         val charCount: Int,
         val iconId: String,
+        val deepLink: String? = null,
     )
 
     @Suppress("MagicNumber")
@@ -180,6 +181,7 @@ class DefaultDocBundleLoader : DocBundleLoader {
                 listOf("bluetooth", "usb", "tcp", "pairing"),
                 4100,
                 "connections",
+                deepLink = "meshtastic://meshtastic/connections",
             ),
             UserPageDef(
                 "messages-and-channels",
@@ -190,6 +192,7 @@ class DefaultDocBundleLoader : DocBundleLoader {
                 listOf("channels", "direct-messages", "messaging", "conversations"),
                 4500,
                 "messages",
+                deepLink = "meshtastic://meshtastic/messages",
             ),
             UserPageDef(
                 "nodes",
@@ -200,6 +203,7 @@ class DefaultDocBundleLoader : DocBundleLoader {
                 listOf("node-list", "mesh-nodes", "peers"),
                 3800,
                 "nodes",
+                deepLink = "meshtastic://meshtastic/nodes",
             ),
             UserPageDef(
                 "node-metrics",
@@ -220,6 +224,7 @@ class DefaultDocBundleLoader : DocBundleLoader {
                 listOf("map", "waypoints", "gps", "location"),
                 3600,
                 "map",
+                deepLink = "meshtastic://meshtastic/map",
             ),
             UserPageDef(
                 "settings-radio-user",
@@ -230,6 +235,7 @@ class DefaultDocBundleLoader : DocBundleLoader {
                 listOf("settings", "radio-config", "user-config", "lora"),
                 6800,
                 "settings-radio",
+                deepLink = "meshtastic://meshtastic/settings",
             ),
             UserPageDef(
                 "settings-module-admin",
@@ -240,6 +246,7 @@ class DefaultDocBundleLoader : DocBundleLoader {
                 listOf("modules", "module-config", "administration"),
                 5500,
                 "settings-module",
+                deepLink = "meshtastic://meshtastic/settings/module-config",
             ),
             UserPageDef(
                 "telemetry-and-sensors",
@@ -290,6 +297,7 @@ class DefaultDocBundleLoader : DocBundleLoader {
                 listOf("firmware", "update", "ota", "flash"),
                 3400,
                 "firmware",
+                deepLink = "meshtastic://meshtastic/firmware",
             ),
             UserPageDef(
                 "desktop",
@@ -344,6 +352,7 @@ class DefaultDocBundleLoader : DocBundleLoader {
             aliases = def.aliases,
             charCount = def.charCount,
             iconId = def.iconId,
+            deepLink = def.deepLink,
         )
     }
 
@@ -464,5 +473,6 @@ class DefaultDocBundleLoader : DocBundleLoader {
         aliases = aliases,
         charCount = charCount,
         iconId = iconId,
+        deepLink = deepLink,
     )
 }
diff --git a/feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/model/DocModels.kt b/feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/model/DocModels.kt
@@ -61,6 +61,8 @@ data class DocPage(
     val charCount: Int,
     /** Icon identifier for TOC display (maps to MeshtasticIcons). */
     val iconId: String? = null,
+    /** Deep link URI to open the corresponding app screen (e.g. `meshtastic://meshtastic/nodes`). */
+    val deepLink: String? = null,
 )
 
 /** Content wrapper that decouples metadata from rendered content. */
@@ -92,6 +94,7 @@ data class KeywordIndexEntry(
     val aliases: List<String> = emptyList(),
     val charCount: Int,
     val iconId: String? = null,
+    val deepLink: String? = null,
 )
 
 /** Normalized user search query. */
diff --git a/feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/navigation/DocsNavigation.kt b/feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/navigation/DocsNavigation.kt
@@ -22,6 +22,7 @@ import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
+import androidx.compose.ui.platform.LocalUriHandler
 import androidx.navigation3.runtime.EntryProviderScope
 import androidx.navigation3.runtime.NavBackStack
 import androidx.navigation3.runtime.NavKey
@@ -97,11 +98,13 @@ private fun DocsPageScreen(pageId: String, backStack: NavBackStack<NavKey>) {
     val backHandlerState = rememberNavigationEventState(NavigationEventInfo.None)
     NavigationBackHandler(state = backHandlerState, onBackCompleted = { backStack.removeLastOrNull() })
 
+    val uriHandler = LocalUriHandler.current
     DocsPageRouteScreen(
         pageId = pageId,
         content = content,
         isLoading = isLoading,
         onBack = { backStack.removeLastOrNull() },
         onNavigateToPage = { targetPageId -> backStack.add(SettingsRoute.HelpDocPage(targetPageId)) },
+        onDeepLink = { deepLinkUri -> uriHandler.openUri(deepLinkUri) },
     )
 }
diff --git a/feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/ui/DocsPageRouteScreen.kt b/feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/ui/DocsPageRouteScreen.kt
@@ -29,6 +29,7 @@ import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Scaffold
 import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
 import androidx.compose.material3.TopAppBar
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider
@@ -40,6 +41,7 @@ import androidx.compose.ui.platform.UriHandler
 import androidx.compose.ui.unit.dp
 import com.mikepenz.markdown.m3.Markdown
 import org.meshtastic.core.ui.icon.ArrowBack
+import org.meshtastic.core.ui.icon.ChevronRight
 import org.meshtastic.core.ui.icon.MeshtasticIcons
 import org.meshtastic.feature.docs.model.DocPageContent
 
@@ -52,6 +54,7 @@ fun DocsPageRouteScreen(
     isLoading: Boolean,
     onBack: () -> Unit,
     onNavigateToPage: (String) -> Unit = {},
+    onDeepLink: (String) -> Unit = {},
     modifier: Modifier = Modifier,
 ) {
     Scaffold(
@@ -63,6 +66,19 @@ fun DocsPageRouteScreen(
                         Icon(imageVector = MeshtasticIcons.ArrowBack, contentDescription = "Navigate back")
                     }
                 },
+                actions = {
+                    val deepLink = content?.page?.deepLink
+                    if (deepLink != null) {
+                        TextButton(onClick = { onDeepLink(deepLink) }) {
+                            Icon(
+                                imageVector = MeshtasticIcons.ChevronRight,
+                                contentDescription = null,
+                                modifier = Modifier.padding(end = 4.dp),
+                            )
+                            Text("Open in App")
+                        }
+                    }
+                },
             )
         },
         modifier = modifier,
@@ -98,8 +114,12 @@ fun DocsPageRouteScreen(
                     val markdownText = content.markdown ?: "No content available."
                     val platformUriHandler = LocalUriHandler.current
                     val docsUriHandler =
-                        remember(platformUriHandler) {
-                            DocsLinkUriHandler(onNavigateToPage = onNavigateToPage, fallback = platformUriHandler)
+                        remember(platformUriHandler, onDeepLink) {
+                            DocsLinkUriHandler(
+                                onNavigateToPage = onNavigateToPage,
+                                onDeepLink = onDeepLink,
+                                fallback = platformUriHandler,
+                            )
                         }
                     CompositionLocalProvider(LocalUriHandler provides docsUriHandler) {
                         Markdown(
@@ -115,18 +135,28 @@ fun DocsPageRouteScreen(
 }
 
 /**
- * Custom [UriHandler] that intercepts relative doc links and navigates in-app.
+ * Custom [UriHandler] that intercepts relative doc links and `meshtastic://` deep links.
  *
- * Relative links like `connections`, `../developer/architecture`, or anchor-only `#section` are resolved to a page ID
- * and dispatched via [onNavigateToPage]. External `http(s)://` URLs are forwarded to the [fallback] platform handler.
+ * - Relative links like `connections`, `../developer/architecture`, or anchor-only `#section` are resolved to a page ID
+ *   and dispatched via [onNavigateToPage].
+ * - `meshtastic://` deep links are dispatched via [onDeepLink] for in-app navigation to the target screen.
+ * - External `http(s)://` URLs are forwarded to the [fallback] platform handler.
  */
-private class DocsLinkUriHandler(private val onNavigateToPage: (String) -> Unit, private val fallback: UriHandler) :
-    UriHandler {
+private class DocsLinkUriHandler(
+    private val onNavigateToPage: (String) -> Unit,
+    private val onDeepLink: (String) -> Unit,
+    private val fallback: UriHandler,
+) : UriHandler {
     override fun openUri(uri: String) {
         if (uri.startsWith("http://") || uri.startsWith("https://")) {
             fallback.openUri(uri)
             return
         }
+        // meshtastic:// deep links navigate to the corresponding app screen
+        if (uri.startsWith("meshtastic://")) {
+            onDeepLink(uri)
+            return
+        }
         // Anchor-only links (e.g. "#permissions") — ignore, stay on current page
         if (uri.startsWith("#")) return
 
diff --git a/scripts/validate-doc-links.js b/scripts/validate-doc-links.js
@@ -36,7 +36,7 @@ forEachDocPage(DOCS_DIR, (filePath, slug, section) => {
         while ((match = linkRe.exec(line)) !== null) {
             const target = match[2];
 
-            if (/^(https?:|mailto:|#)/.test(target)) continue;
+            if (/^(https?:|mailto:|#|meshtastic:)/.test(target)) continue;
 
             const ext = path.extname(target).toLowerCase();
             if (IMAGE_EXTS.has(ext)) continue;

Original file line number	Diff line number	Diff line change
`@@ -61,6 +61,8 @@ data class DocPage(`
`61`	`61`	`val charCount: Int,`
`62`	`62`	`/** Icon identifier for TOC display (maps to MeshtasticIcons). */`
`63`	`63`	`val iconId: String? = null,`
	`64`	+ /** Deep link URI to open the corresponding app screen (e.g. `meshtastic://meshtastic/nodes`). */
	`65`	`+ val deepLink: String? = null,`
`64`	`66`	`)`
`65`	`67`
`66`	`68`	`/** Content wrapper that decouples metadata from rendered content. */`
`@@ -92,6 +94,7 @@ data class KeywordIndexEntry(`
`92`	`94`	`val aliases: List<String> = emptyList(),`
`93`	`95`	`val charCount: Int,`
`94`	`96`	`val iconId: String? = null,`
	`97`	`+ val deepLink: String? = null,`
`95`	`98`	`)`
`96`	`99`
`97`	`100`	`/** Normalized user search query. */`