docs: let a section's redirect stub still group and title its section

Eight of the twelve docs sections were missing from the sidebar's grouping:
admin, cloud, contribute, device-agent, hardware, install, migration and user.
They appeared under a catch-all "Other" heading, titled by raw path segment
("user", "admin"), and the Device Agent, FlowFuse Cloud and Contributing groups
came out empty and were filtered away, so they did not render at all.

The cause: each of those section index pages is a `layout: redirect` stub
pointing at the section's introduction page, and buildDocsNav dropped every
page carrying `redirect`. Dropping them was right as far as linking goes -
a sidebar entry pointing at a URL that 301s makes nuxt-link-checker's
`redirects` inspection flag every docs page - but it also threw away the
navGroup, navGroupOrder, navTitle and navOrder those pages carry. With the
index gone, the section node was built only from the paths of its children,
which have no group of their own.

So the frontmatter is kept and applied to the node the children create, and
only the link is withheld. `link: false` marks such a node as a label rather
than a destination; navigationMenu omits `to` for it. The node keeps its own
path, which is what the menu's auto-expand and the breadcrumb trail match on,
so both now work through a stubbed section and breadcrumbs read "Using
FlowFuse" rather than "user".

A stub with no pages beneath it still contributes nothing, so leaf redirects
like docs/community-support.md do not become dead, unclickable labels.

This is a fix to the nav builder only. Every group name, order and title it now
honours was already declared in FlowFuse/flowfuse; nothing changes there.

Author: dimitrieh

nuxt/composables/useDocsNav.ts

@@ -10,6 +10,8 @@ export interface DocsNavNode {
     group?: string
     groupOrder?: number
     order: number
+    // false when this section's index page is a redirect stub - see nuxt/lib/docs-nav.mjs.
+    link?: boolean
     children: DocsNavNode[]
 }
 

nuxt/lib/docs-nav.mjs

@@ -10,6 +10,33 @@
 
 import { findPageBreadcrumb } from '@nuxt/content/utils'
 
+const stripSlash = path => (path.endsWith('/') ? path.slice(0, -1) : path) || '/'
+
+/**
+ * Give each node the frontmatter of the redirect stub sitting at its path, if there is one.
+ *
+ * `link: false` marks it as a label rather than a destination: nuxt/utils/navigationMenu.ts
+ * omits `to` for those, so the branch is still titled, grouped and expandable without the
+ * sidebar ever pointing at a URL that 301s. The node keeps its own path, which is what the
+ * menu's auto-expand and the breadcrumb trail match on.
+ *
+ * @param {Array<{path: string, title: string, group?: string, groupOrder?: number, order: number, children: Array}>} nodes
+ * @param {Map<string, {navTitle?: string|null, title?: string|null, navGroup?: string|null, navGroupOrder?: number|null, navOrder?: number|null}>} stubs
+ */
+function applyStubFrontmatter (nodes, stubs) {
+    for (const node of nodes) {
+        const stub = stubs.get(stripSlash(node.path))
+        if (stub) {
+            node.title = stub.navTitle || stub.title || node.title
+            if (stub.navGroup != null) node.group = stub.navGroup
+            if (stub.navGroupOrder != null) node.groupOrder = stub.navGroupOrder
+            if (stub.navOrder != null) node.order = stub.navOrder
+            node.link = false
+        }
+        applyStubFrontmatter(node.children, stubs)
+    }
+}
+
 /**
  * @param {Array<{path: string, title?: string|null, navTitle?: string|null, navOrder?: number|null, navGroup?: string|null, navGroupOrder?: number|null, redirect?: {to: string}|null}>} pages
  */
@@ -19,8 +46,24 @@ export function buildDocsNav (pages) {
     // A page whose only purpose is `redirect: { to }` (e.g. FlowFuse/flowfuse's
     // docs/admin/licensing.md and docs/community-support.md) has no content of its own to
     // link to from the sidebar. Rendering it as a nav entry means every single docs page
-    // gets flagged by nuxt-link-checker's `redirects` inspection, so it's left out.
-    const linkable = pages.filter(page => !page.redirect)
+    // gets flagged by nuxt-link-checker's `redirects` inspection, so it never becomes a
+    // link target.
+    //
+    // Its frontmatter still matters though. Most section index pages in FlowFuse/flowfuse
+    // are redirect stubs (docs/user, docs/install, docs/admin, docs/cloud, docs/device-agent,
+    // docs/hardware, docs/migration, docs/contribute), and each one carries the navGroup,
+    // navGroupOrder, navTitle and navOrder that its whole section is grouped, labelled and
+    // ranked by. Discarding the page discarded that too, so those sections were built only
+    // from the paths of their children: no group (they fell into "Other"), and titled by raw
+    // path segment ("user", "admin"). Three groups had every member stubbed and vanished
+    // entirely. So the metadata is kept here and applied to the node the children create,
+    // and only the link is withheld.
+    const linkable = []
+    const stubs = new Map()
+    for (const page of pages) {
+        if (page.redirect) stubs.set(stripSlash(page.path), page)
+        else linkable.push(page)
+    }
 
     const sorted = [...linkable].sort((a, b) => {
         const depthA = a.path.split('/').filter(Boolean).length
@@ -76,6 +119,9 @@ export function buildDocsNav (pages) {
     }
 
     const root = toDocsNavNodes(tree)
+    // Before grouping and sorting, which both read these fields.
+    applyStubFrontmatter(root, stubs)
+
     const docsRoot = root.find(n => n.path === '/docs')
     if (!docsRoot) return []
 

nuxt/lib/docs-nav.test.mjs

@@ -126,3 +126,84 @@ 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'), [])
 })
+
+// Most section index pages in FlowFuse/flowfuse are `layout: redirect` stubs pointing at
+// the section's introduction page. They still carry the frontmatter the section is
+// grouped, labelled and ranked by.
+function redirectStub (path, { group, groupOrder, order, navTitle } = {}) {
+    return { ...section(path, { group, groupOrder, order, navTitle }), redirect: { to: path + '/introduction' } }
+}
+
+test('a redirect stub still groups, titles and ranks the section its children create', () => {
+    const nav = buildDocsNav([
+        redirectStub('/docs/user', { group: 'User Manuals', groupOrder: 1, order: 1, navTitle: 'Using FlowFuse' }),
+        section('/docs/user/introduction', { order: 1, navTitle: 'Introduction' }),
+        section('/docs/user/concepts', { order: 2, navTitle: 'Concepts' }),
+    ])
+
+    assert.deepEqual(names(nav), ['User Manuals'])
+    const user = nav[0].children[0]
+    assert.equal(user.title, 'Using FlowFuse')
+    assert.equal(user.path, '/docs/user')
+    assert.deepEqual(user.children.map(c => c.title), ['Introduction', 'Concepts'])
+})
+
+test('a redirect stub is not a link target, so the sidebar never points at a 301', () => {
+    const nav = buildDocsNav([
+        redirectStub('/docs/user', { group: 'User Manuals', groupOrder: 1, navTitle: 'Using FlowFuse' }),
+        section('/docs/user/introduction', { order: 1, navTitle: 'Introduction' }),
+    ])
+
+    assert.equal(nav[0].children[0].link, false)
+    // A real page in the same position stays linkable.
+    const real = buildDocsNav([section('/docs/quick-start', { group: 'G', groupOrder: 1 })])
+    assert.notEqual(real[0].children[0].link, false)
+})
+
+test('a group whose sections are all redirect stubs still renders', () => {
+    // Device Agent, FlowFuse Cloud and Contributing each had every member stubbed, so the
+    // group came out empty and was filtered away entirely.
+    const nav = buildDocsNav([
+        redirectStub('/docs/device-agent', { group: 'Device Agent', groupOrder: 2, order: 1, navTitle: 'Device Agent' }),
+        section('/docs/device-agent/quickstart', { order: 1, navTitle: 'Quickstart' }),
+        redirectStub('/docs/hardware', { group: 'Device Agent', groupOrder: 2, order: 2, navTitle: 'Hardware Guides' }),
+        section('/docs/hardware/raspbian', { order: 1, navTitle: 'Raspberry Pi' }),
+    ])
+
+    assert.deepEqual(names(nav), ['Device Agent'])
+    assert.deepEqual(nav[0].children.map(c => c.title), ['Device Agent', 'Hardware Guides'])
+})
+
+test('a stubbed section no longer falls into Other titled by its path segment', () => {
+    const nav = buildDocsNav([
+        redirectStub('/docs/admin', { group: 'Self-Hosted', groupOrder: 4, order: 4, navTitle: 'Administering FlowFuse' }),
+        section('/docs/admin/introduction', { order: 1, navTitle: 'Introduction' }),
+        section('/docs/quick-start', { group: 'Self-Hosted', groupOrder: 4, order: 1, navTitle: 'Quick Start' }),
+    ])
+
+    assert.deepEqual(names(nav), ['Self-Hosted'])
+    assert.deepEqual(nav[0].children.map(c => c.title), ['Quick Start', 'Administering FlowFuse'])
+})
+
+test('a redirect stub with no pages beneath it contributes nothing', () => {
+    // docs/admin/licensing.md and docs/community-support.md are leaf redirects with no
+    // children; they should not appear as dead, unclickable labels.
+    const nav = buildDocsNav([
+        section('/docs/debugging', { group: 'Support', groupOrder: 5, navTitle: 'Debugging' }),
+        redirectStub('/docs/community-support', { group: 'Support', groupOrder: 5 }),
+    ])
+
+    assert.deepEqual(nav[0].children.map(c => c.title), ['Debugging'])
+})
+
+test('breadcrumbs through a stubbed section use its real title', () => {
+    const nav = buildDocsNav([
+        redirectStub('/docs/user', { group: 'User Manuals', groupOrder: 1, navTitle: 'Using FlowFuse' }),
+        section('/docs/user/concepts', { order: 1, navTitle: 'Concepts' }),
+    ])
+
+    assert.deepEqual(
+        findDocsBreadcrumb(nav, '/docs/user/concepts').map(c => c.title),
+        ['Using FlowFuse', 'Concepts'],
+    )
+})

nuxt/utils/navigationMenu.ts

@@ -7,6 +7,10 @@ export interface MenuTreeNode {
     title: string
     path: string
     icon?: string
+    // false for a branch whose index page only redirects (see nuxt/lib/docs-nav.mjs): it
+    // still titles, groups and expands the branch, but must not be a link target. `path`
+    // stays set either way - auto-expand below matches on it.
+    link?: boolean
     children?: MenuTreeNode[]
 }
 
@@ -22,7 +26,7 @@ export function buildNavigationMenuItems(nodes: MenuTreeNode[], currentPath: str
         const children = node.children?.length ? buildNavigationMenuItems(node.children, currentPath) : undefined
         return {
             label: node.title,
-            to: node.path,
+            ...(node.link === false ? {} : { to: node.path }),
             icon: node.icon,
             defaultOpen: children ? isOrContains(node.path, currentPath) : undefined,
             children,