From 9c312539dddd6e602aa7706b4153adaa6a38e9b7 Mon Sep 17 00:00:00 2001
From: ZJ van de Weg <git@zjvandeweg.nl>
Date: Tue, 11 Aug 2026 10:51:43 -0700
Subject: [PATCH] Add schema.org breadcrumbs for docs, share one component with
 handbook

Docs had no BreadcrumbList structured data at all - just a plain <nav>
built from raw URL segments (no real page titles). Handbook had schema
markup, but via a call duplicated in the page's script, separate from
the visual breadcrumb component, and both were subtly wrong: nuxt/content's
findPageBreadcrumb() excludes the current page by default, so the existing
`.slice(0, -1)` (meant to drop the current page) was actually dropping the
true parent crumb, and the current page was never in the schema at all.

Fixes:
- New shared nuxt/components/Breadcrumbs.vue renders the visual trail and
  registers the matching BreadcrumbList in one place, so a page can't
  show one without the other going stale. Every crumb gets a ListItem
  (including the current page) - schema.org only makes `item` optional
  for the last entry, not the entry itself.
- Renamed DocsNavNode's `name` field to `title`, matching @nuxt/content's
  ContentNavigationItem shape, so docs can reuse @nuxt/content's own
  findPageBreadcrumb() (via a small findDocsBreadcrumb() flatten-and-
  delegate wrapper, since groups themselves aren't pages) instead of a
  bespoke tree walker.
- Extracted useDocsNavTree() so the docs page and DocsLeftNav share one
  useAsyncData('docs-nav', ...) call - they'd started emitting a "did you
  mean to use a different handler" dev warning once both called it.
- Docs breadcrumbs now show real page titles instead of raw URL segments.

Verified locally: /docs/admin/sso/ldap and /handbook/design/design-thinking
both render the correct visible trail and a complete BreadcrumbList with
position 1..N, terminating in the current page.
---
 nuxt/components/Breadcrumbs.vue         | 32 +++++++++++++++++++++++
 nuxt/components/DocsLeftNav.vue         | 23 ++++++-----------
 nuxt/components/HandbookBreadcrumbs.vue | 33 ------------------------
 nuxt/composables/useDocsNav.ts          | 12 +++++++--
 nuxt/lib/docs-nav.mjs                   | 28 +++++++++++++++-----
 nuxt/lib/docs-nav.test.mjs              | 34 ++++++++++++++++++++-----
 nuxt/pages/docs/[...slug].vue           | 29 ++++++++++-----------
 nuxt/pages/handbook/[...slug].vue       | 18 ++++++++-----
 8 files changed, 124 insertions(+), 85 deletions(-)
 create mode 100644 nuxt/components/Breadcrumbs.vue
 delete mode 100644 nuxt/components/HandbookBreadcrumbs.vue

diff --git a/nuxt/components/Breadcrumbs.vue b/nuxt/components/Breadcrumbs.vue
new file mode 100644
index 0000000000..cb3680bd62
--- /dev/null
+++ b/nuxt/components/Breadcrumbs.vue
@@ -0,0 +1,32 @@
+<script setup lang="ts">
+// Shared by docs, handbook to render the visual breadcrumb and registers the
+// matching schema.org BreadcrumbList in one place, so a page are up to date.
+interface BreadcrumbItem {
+    label: string
+    to?: string
+}
+
+const props = defineProps<{ items: BreadcrumbItem[] }>()
+
+useSchemaOrg([
+    defineBreadcrumb({
+        itemListElement: props.items.map(item => ({
+            name: item.label,
+            ...(item.to ? { item: item.to } : {}),
+        })),
+    }),
+])
+</script>
+
+<template>
+  <UBreadcrumb
+    :items="items"
+    color="neutral"
+    class="capitalize"
+    :ui="{ link: 'text-sm hover:text-indigo-600' }"
+  >
+    <template #separator>
+      <span class="mx-1 text-gray-400">/</span>
+    </template>
+  </UBreadcrumb>
+</template>
diff --git a/nuxt/components/DocsLeftNav.vue b/nuxt/components/DocsLeftNav.vue
index e88f0d38fd..ed7bdd3c8a 100644
--- a/nuxt/components/DocsLeftNav.vue
+++ b/nuxt/components/DocsLeftNav.vue
@@ -1,16 +1,9 @@
 <script setup lang="ts">
-import { buildDocsNav, type DocsNavNode, type DocsNavGroup } from '~/composables/useDocsNav'
+import { useDocsNavTree, type DocsNavNode, type DocsNavGroup } from '~/composables/useDocsNav'
 
 const route = useRoute()
 
-const { data: pages } = await useAsyncData('docs-nav', () =>
-    queryCollection('docs').all()
-)
-
-const navGroups = computed<DocsNavGroup[]>(() => {
-    if (!pages.value) return []
-    return buildDocsNav(pages.value as any[])
-})
+const { data: navGroups } = await useDocsNavTree()
 
 function normPath(p: string) {
     return p.replace(/\/$/, '') || '/'
@@ -53,16 +46,16 @@ function ulStyle(node: DocsNavNode) {
         <NuxtLink href="/docs">Documentation</NuxtLink>
       </li>
 
-      <template v-for="group in navGroups" :key="group.name">
+      <template v-for="group in navGroups ?? []" :key="group.name">
         <li class="handbook-nav-group">{{ group.name }}</li>
 
         <template v-for="entry in group.children" :key="entry.path">
           <li :class="{ active: isActive(entry.path), open: isOpen(entry) && entry.children.length > 0 }">
-            <NuxtLink :href="entry.path">{{ entry.name }}</NuxtLink>
+            <NuxtLink :href="entry.path">{{ entry.title }}</NuxtLink>
             <button v-if="entry.children.length"
               @click="toggle(entry.path)"
               :aria-expanded="isOpen(entry).toString()"
-              :aria-label="`Toggle ${entry.name} submenu`">
+              :aria-label="`Toggle ${entry.title} submenu`">
               <span class="ff-icon icon-expand">
                 <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>
               </span>
@@ -76,11 +69,11 @@ function ulStyle(node: DocsNavNode) {
             <ul class="handbook-nav-nested" :style="ulStyle(entry)">
               <template v-for="child in entry.children" :key="child.path">
                 <li :class="{ active: isActive(child.path), open: isOpen(child) && child.children.length > 0 }">
-                  <NuxtLink :href="child.path">{{ child.name }}</NuxtLink>
+                  <NuxtLink :href="child.path">{{ child.title }}</NuxtLink>
                   <button v-if="child.children.length"
                     @click="toggle(child.path)"
                     :aria-expanded="isOpen(child).toString()"
-                    :aria-label="`Toggle ${child.name} submenu`">
+                    :aria-label="`Toggle ${child.title} submenu`">
                     <span class="ff-icon icon-expand">
                       <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>
                     </span>
@@ -94,7 +87,7 @@ function ulStyle(node: DocsNavNode) {
                   <ul class="handbook-nav-nested-2" :style="ulStyle(child)">
                     <li v-for="grandchild in child.children" :key="grandchild.path"
                       :class="{ active: isActive(grandchild.path) }">
-                      <NuxtLink :href="grandchild.path">{{ grandchild.name }}</NuxtLink>
+                      <NuxtLink :href="grandchild.path">{{ grandchild.title }}</NuxtLink>
                     </li>
                   </ul>
                 </li>
diff --git a/nuxt/components/HandbookBreadcrumbs.vue b/nuxt/components/HandbookBreadcrumbs.vue
deleted file mode 100644
index 2afca817ea..0000000000
--- a/nuxt/components/HandbookBreadcrumbs.vue
+++ /dev/null
@@ -1,33 +0,0 @@
-<script setup lang="ts">
-const route = useRoute()
-
-const slugParts = computed(() =>
-    Array.isArray(route.params.slug) ? route.params.slug : [route.params.slug].filter(Boolean)
-)
-
-const items = computed(() => {
-    const parts = ['handbook', ...slugParts.value]
-    let path = ''
-    return parts.map((part, i) => {
-        path += '/' + part
-        const isLast = i === parts.length - 1
-        return {
-            label: part.replace(/-/g, ' '),
-            ...(isLast ? {} : { to: path }),
-        }
-    })
-})
-</script>
-
-<template>
-  <UBreadcrumb
-    :items="items"
-    color="neutral"
-    class="capitalize"
-    :ui="{ link: 'text-sm hover:text-indigo-600' }"
-  >
-    <template #separator>
-      <span class="mx-1 text-gray-400">/</span>
-    </template>
-  </UBreadcrumb>
-</template>
diff --git a/nuxt/composables/useDocsNav.ts b/nuxt/composables/useDocsNav.ts
index 51892bed01..9a38efbb11 100644
--- a/nuxt/composables/useDocsNav.ts
+++ b/nuxt/composables/useDocsNav.ts
@@ -1,10 +1,11 @@
 // The builder lives in nuxt/lib/ as plain JS so `node --test` can run it directly
 // (same reason as docs-sync.mjs); this file is the typed surface components import.
 // @ts-ignore untyped module
-import { buildDocsNav as build } from '../lib/docs-nav.mjs'
+import { buildDocsNav as build, findDocsBreadcrumb as findBreadcrumb } from '../lib/docs-nav.mjs'
 
 export interface DocsNavNode {
-    name: string
+    // Matches @nuxt/content's ContentNavigationItem shape (title/path/children)
+    title: string
     path: string
     group?: string
     groupOrder?: number
@@ -38,3 +39,10 @@ export interface DocsNavPage {
 export function buildDocsNav (pages: DocsNavPage[]): DocsNavGroup[] {
     return build(pages)
 }
+
+export function findDocsBreadcrumb (groups: DocsNavGroup[], path: string): DocsNavNode[] {
+    return findBreadcrumb(groups, path)
+}
+
+export const useDocsNavTree = () =>
+    useAsyncData('docs-nav', async () => buildDocsNav(await queryCollection('docs').all() as DocsNavPage[]))
diff --git a/nuxt/lib/docs-nav.mjs b/nuxt/lib/docs-nav.mjs
index c6ad114218..e9dd7ffaea 100644
--- a/nuxt/lib/docs-nav.mjs
+++ b/nuxt/lib/docs-nav.mjs
@@ -8,6 +8,8 @@
 // `navOrder` ranks pages within one. Nothing about the structure is declared here, so
 // restructuring the docs is a change in the docs repo alone.
 
+import { findPageBreadcrumb } from '@nuxt/content/utils'
+
 /**
  * @param {Array<{path: string, title?: string|null, navTitle?: string|null, navOrder?: number|null, navGroup?: string|null, navGroupOrder?: number|null, redirect?: {to: string}|null}>} pages
  */
@@ -33,11 +35,11 @@ export function buildDocsNav (pages) {
         for (let i = 0; i < parts.length; i++) {
             const part = parts[i]
             const isLeaf = i === parts.length - 1
-            const displayName = isLeaf ? (page.navTitle || page.title || part) : part
+            const displayTitle = isLeaf ? (page.navTitle || page.title || part) : part
 
             if (!current[part]) {
                 current[part] = {
-                    name: displayName,
+                    title: displayTitle,
                     path: '/' + parts.slice(0, i + 1).join('/'),
                     group: isLeaf ? (page.navGroup ?? undefined) : undefined,
                     groupOrder: isLeaf ? (page.navGroupOrder ?? undefined) : undefined,
@@ -45,8 +47,8 @@ export function buildDocsNav (pages) {
                     children: {},
                 }
             } else if (isLeaf) {
-                // Update name/group/order when we reach the leaf for this node
-                current[part].name = displayName
+                // Update title/group/order when we reach the leaf for this node
+                current[part].title = displayTitle
                 current[part].group = page.navGroup ?? undefined
                 current[part].groupOrder = page.navGroupOrder ?? undefined
                 current[part].order = page.navOrder ?? Infinity
@@ -58,7 +60,7 @@ export function buildDocsNav (pages) {
 
     function toDocsNavNodes (obj) {
         return Object.values(obj).map(node => ({
-            name: node.name,
+            title: node.title,
             path: node.path,
             group: node.group,
             groupOrder: node.groupOrder,
@@ -69,7 +71,7 @@ export function buildDocsNav (pages) {
 
     function sortNodes (nodes) {
         return nodes
-            .sort((a, b) => (a.order - b.order) || a.name.localeCompare(b.name))
+            .sort((a, b) => (a.order - b.order) || a.title.localeCompare(b.title))
             .map(n => ({ ...n, children: sortNodes(n.children) }))
     }
 
@@ -97,3 +99,17 @@ export function buildDocsNav (pages) {
         .filter(g => g.children.length > 0)
         .sort((a, b) => (a.order - b.order) || a.name.localeCompare(b.name))
 }
+
+/**
+ * Ancestor chain for a docs path, for breadcrumbs. Groups themselves aren't pages (no
+ * `path` of their own), so this flattens straight to their sections before handing off
+ * to @nuxt/content's own findPageBreadcrumb - same helper handbook uses.
+ *
+ * @param {ReturnType<typeof buildDocsNav>} groups
+ * @param {string} path
+ */
+export function findDocsBreadcrumb (groups, path) {
+    // findPageBreadcrumb excludes the current page by default - callers here want the
+    // full chain (they decide themselves whether the last crumb should link anywhere).
+    return findPageBreadcrumb(groups.flatMap(g => g.children), path, { current: true })
+}
diff --git a/nuxt/lib/docs-nav.test.mjs b/nuxt/lib/docs-nav.test.mjs
index fe2d6db381..567589182d 100644
--- a/nuxt/lib/docs-nav.test.mjs
+++ b/nuxt/lib/docs-nav.test.mjs
@@ -1,7 +1,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { buildDocsNav } from './docs-nav.mjs'
+import { buildDocsNav, findDocsBreadcrumb } from './docs-nav.mjs'
 
 // A section is a direct child of /docs; its index page carries the group frontmatter.
 function section (path, { group, groupOrder, order, navTitle } = {}) {
@@ -85,22 +85,44 @@ test('deeper pages nest under their section and keep navOrder', () => {
     ])
 
     const user = nav[0].children[0]
-    assert.equal(user.name, 'Using FlowFuse')
-    assert.deepEqual(user.children.map(c => c.name), ['Introduction', 'Concepts', 'teams'])
-    assert.deepEqual(user.children[2].children.map(c => c.name), ['Billing'])
+    assert.equal(user.title, 'Using FlowFuse')
+    assert.deepEqual(user.children.map(c => c.title), ['Introduction', 'Concepts', 'teams'])
+    assert.deepEqual(user.children[2].children.map(c => c.title), ['Billing'])
 })
 
-test('name falls back to title then to the path segment', () => {
+test('title falls back to the page title then to the path segment', () => {
     const nav = buildDocsNav([
         { path: '/docs/a', navGroup: 'G', navGroupOrder: 1, navOrder: 1, navTitle: 'Nav wins', title: 'Title loses' },
         { path: '/docs/b', navGroup: 'G', navGroupOrder: 1, navOrder: 2, title: 'Title used' },
         { path: '/docs/c', navGroup: 'G', navGroupOrder: 1, navOrder: 3 },
     ])
 
-    assert.deepEqual(nav[0].children.map(c => c.name), ['Nav wins', 'Title used', 'c'])
+    assert.deepEqual(nav[0].children.map(c => c.title), ['Nav wins', 'Title used', 'c'])
 })
 
 test('pages outside /docs are ignored', () => {
     assert.deepEqual(buildDocsNav([section('/handbook/company', { group: 'Company', groupOrder: 1 })]), [])
     assert.deepEqual(buildDocsNav([]), [])
 })
+
+test('findDocsBreadcrumb returns the real-title ancestor chain, spanning groups', () => {
+    const nav = buildDocsNav([
+        section('/docs/user', { group: 'User Manuals', groupOrder: 1, navTitle: 'Using FlowFuse' }),
+        section('/docs/user/teams/billing', { order: 1, navTitle: 'Billing' }),
+        section('/docs/cloud', { group: 'Cloud', groupOrder: 2, navTitle: 'FlowFuse Cloud' }),
+    ])
+
+    assert.deepEqual(
+        findDocsBreadcrumb(nav, '/docs/user/teams/billing').map(c => [c.title, c.path]),
+        [
+            ['Using FlowFuse', '/docs/user'],
+            ['teams', '/docs/user/teams'],
+            ['Billing', '/docs/user/teams/billing'],
+        ],
+    )
+})
+
+test('findDocsBreadcrumb returns nothing for an unknown path', () => {
+    const nav = buildDocsNav([section('/docs/user', { group: 'User Manuals', groupOrder: 1 })])
+    assert.deepEqual(findDocsBreadcrumb(nav, '/docs/nonexistent'), [])
+})
diff --git a/nuxt/pages/docs/[...slug].vue b/nuxt/pages/docs/[...slug].vue
index 5ea509a1e4..055c04bcc9 100644
--- a/nuxt/pages/docs/[...slug].vue
+++ b/nuxt/pages/docs/[...slug].vue
@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import { useDocsNavTree, findDocsBreadcrumb } from '~/composables/useDocsNav'
+
 definePageMeta({ layout: 'default' })
 
 const route = useRoute()
@@ -34,13 +36,16 @@ useHead({
     ],
 })
 
-const breadcrumbs = computed(() => {
-    const parts = ['docs', ...slugParts.value]
-    let path = ''
-    return parts.map(part => {
-        path += '/' + part
-        return { name: part, path }
-    })
+// Same key+handler DocsLeftNav uses, so useAsyncData dedupes into one fetch per request.
+const { data: navGroups } = await useDocsNavTree()
+
+const breadcrumbItems = computed(() => {
+    const crumbs = findDocsBreadcrumb(navGroups.value ?? [], route.path)
+    const withRoot = [{ title: 'Docs', path: '/docs' }, ...crumbs]
+    return withRoot.map((crumb, i) => ({
+        label: crumb.title,
+        ...(i === withRoot.length - 1 ? {} : { to: crumb.path }),
+    }))
 })
 </script>
 
@@ -57,15 +62,7 @@ const breadcrumbs = computed(() => {
           <!-- Breadcrumbs + Search bar -->
           <div class="font-medium pb-1 flex flex-col gap-1">
             <div class="md:flex-1">
-              <nav aria-label="Breadcrumb" class="text-sm text-gray-500">
-                <span v-for="(crumb, i) in breadcrumbs" :key="crumb.path">
-                  <NuxtLink v-if="i < breadcrumbs.length - 1"
-                    :href="crumb.path"
-                    class="hover:text-indigo-600 capitalize">{{ crumb.name }}</NuxtLink>
-                  <span v-else class="capitalize text-gray-700">{{ crumb.name }}</span>
-                  <span v-if="i < breadcrumbs.length - 1" class="mx-1">/</span>
-                </span>
-              </nav>
+              <Breadcrumbs :items="breadcrumbItems" />
             </div>
             <div class="w-full mb-1">
               <AlgoliaSearch index-filter="category:docs" placeholder="Search in Docs..." source-id="docs" />
diff --git a/nuxt/pages/handbook/[...slug].vue b/nuxt/pages/handbook/[...slug].vue
index 9a1e018255..6ec7313a13 100644
--- a/nuxt/pages/handbook/[...slug].vue
+++ b/nuxt/pages/handbook/[...slug].vue
@@ -42,13 +42,17 @@ const githubEditUrl = computed(() => {
     return `https://github.com/FlowFuse/website/edit/main/nuxt/content/${stem}.md`
 })
 
+const breadcrumbItems = computed(() => {
+    // findPageBreadcrumb excludes the current page unless told otherwise - `current: true`
+    // includes it so it can be the last, unlinked crumb below.
+    const crumbs = findPageBreadcrumb(navTree.value ?? [], route.path, { current: true })
+    return crumbs.map((crumb, i) => ({
+        label: crumb.title ?? '',
+        ...(i === crumbs.length - 1 ? {} : { to: crumb.path }),
+    }))
+})
+
 useSchemaOrg([
-    // Exclude the last crumb (current page) — nuxt-schema-org appends it automatically
-    defineBreadcrumb({
-        itemListElement: findPageBreadcrumb(navTree.value ?? [], route.path)
-            .slice(0, -1)
-            .map(crumb => ({ name: crumb.title, item: crumb.path })),
-    }),
     defineArticle({
         headline: pageTitle,
         description: computed(() => page.value?.description || ''),
@@ -75,7 +79,7 @@ defineOgImage('Default', {
           <!-- Breadcrumbs + Search bar -->
           <div class="font-medium pb-1 flex flex-col gap-1">
             <div class="md:flex-1">
-              <HandbookBreadcrumbs />
+              <Breadcrumbs :items="breadcrumbItems" />
             </div>
             <div class="w-full mb-1">
               <HandbookSearch />