docs(site): multilevel nav & IA redesign proposal (Lume nav plugin)

docs/site/_components/breadcrumb.vto

@@ -1,38 +1,52 @@
-{{# breadcrumb.vto — derives a Home / Section / Page trail from the current page
-   url matched against navSections. Both pageUrl and the candidate hrefs are
-   base-prefixed via the `url` filter so they compare on equal footing (same
-   rule as the sidebar active-highlight). On the home page the trail collapses
-   to just "Home" (rendered as plain text, no link). All colors key off the
-   existing fresh-ui --ns-* tokens. #}}
+{{# breadcrumb.vto — lane-prefixed trail derived from nav.breadcrumb(url)
+   (root→page order), prefixed with the owning navLanes lane label so
+   /web-layer/query/ reads Home / Build / Web Layer / Data loading & cache.
+   Node/page urls are SOURCE urls (source==source); emitted hrefs are
+   base-prefixed via the `url` filter. Pages outside the nav tree (nav_hide,
+   redirect shims, the how-to catalog) fall back to Home / <title>. #}}
 {{ set homeUrl = "/" |> url }}
-{{ set pageUrl = url |> url }}
 
-{{# Build the trail: always start with Home. Then, unless we ARE home, find the
-   nav section + item this page belongs to and append section label + page. #}}
-{{ set crumbSection = null }}
-{{ set crumbItem = null }}
-{{ for section of navSections }}
-  {{ for item of section.items }}
-    {{ set itemUrl = item.href |> url }}
-    {{ if itemUrl !== homeUrl && pageUrl.startsWith(itemUrl) }}
-      {{ set crumbSection = section }}
-      {{ set crumbItem = item }}
-    {{ /if }}
-  {{ /for }}
+{{ set laneLabel = null }}
+{{ for lane of navLanes }}
+  {{ if lane.kind === "flat" }}
+    {{ for item of lane.items }}
+      {{ if url === item.href }}{{ set laneLabel = lane.label }}{{ /if }}
+    {{ /for }}
+  {{ else }}
+    {{ for root of lane.roots }}
+      {{ if url.startsWith(root) }}{{ set laneLabel = lane.label }}{{ /if }}
+    {{ /for }}
+  {{ /if }}
 {{ /for }}
 
+{{ set crumbs = nav.breadcrumb(url, navQuery, navSort) }}
+
 <nav class="ns-breadcrumb" aria-label="Breadcrumb">
   <ol class="ns-breadcrumb__list">
-    {{ if pageUrl === homeUrl }}
+    {{ if url === "/" }}
       <li class="ns-breadcrumb__item" aria-current="page">Home</li>
     {{ else }}
       <li class="ns-breadcrumb__item"><a href="{{ homeUrl }}">Home</a></li>
-      {{ if crumbSection }}
+      {{ if laneLabel }}
+        <li class="ns-breadcrumb__sep" aria-hidden="true">/</li>
+        <li class="ns-breadcrumb__item">{{ laneLabel }}</li>
+      {{ /if }}
+      {{ set rendered = 0 }}
+      {{ for crumb of crumbs }}
+        {{ if crumb.data && crumb.data.url !== "/" }}
+          <li class="ns-breadcrumb__sep" aria-hidden="true">/</li>
+          {{ if crumb.data.url === url }}
+            <li class="ns-breadcrumb__item" aria-current="page">{{ crumb.data.nav_title || crumb.data.title }}</li>
+          {{ else }}
+            <li class="ns-breadcrumb__item"><a href="{{ crumb.data.url |> url }}">{{ crumb.data.nav_title || crumb.data.title }}</a></li>
+          {{ /if }}
+          {{ set rendered = rendered + 1 }}
+        {{ /if }}
+      {{ /for }}
+      {{ if rendered === 0 }}
         <li class="ns-breadcrumb__sep" aria-hidden="true">/</li>
-        <li class="ns-breadcrumb__item">{{ crumbSection.label }}</li>
+        <li class="ns-breadcrumb__item" aria-current="page">{{ title }}</li>
       {{ /if }}
-      <li class="ns-breadcrumb__sep" aria-hidden="true">/</li>
-      <li class="ns-breadcrumb__item" aria-current="page">{{ if crumbItem }}{{ crumbItem.label }}{{ else }}{{ title }}{{ /if }}</li>
     {{ /if }}
   </ol>
 </nav>

docs/site/_components/nextPrev.vto

@@ -1,20 +1,38 @@
-{{# nextPrev.vto — prev/next pager rendered at the foot of the article. Pages
-   opt in by setting `prev` and/or `next` front-matter vars, each shaped
-   { label, href }. If neither is present nothing renders. Hrefs are authored
-   root-relative (e.g. /quickstart/) and base-prefixed here via the `url`
-   filter. Colors key off the existing fresh-ui --ns-* tokens. #}}
-{{ if prev || next }}
+{{# nextPrev.vto — prev/next pager rendered at the foot of the article.
+   Two sources, front matter first:
+   1. Pages may set `prev`/`next` front-matter vars ({ label, href }) — the
+      tutorial tracks keep per-chapter editorial control this way.
+   2. Reference pages (32 generated units — unmaintainable by hand) auto-derive
+      neighbours from the nav tree via nav.nextPage/previousPage(url, query,
+      sort) — the verified v2.5.4 signature has NO basePath argument; the
+      `url^=/reference/` query term scopes the walk to the reference lane.
+   Hrefs are source urls, base-prefixed via the `url` filter. #}}
+{{ set prevLink = null }}
+{{ set nextLink = null }}
+{{ if prev }}{{ set prevLink = { label: prev.label, href: prev.href } }}{{ /if }}
+{{ if next }}{{ set nextLink = { label: next.label, href: next.href } }}{{ /if }}
+{{ if url && url.startsWith("/reference/") }}
+  {{ if !prevLink }}
+    {{ set autoPrev = nav.previousPage(url, "url^=/reference/ " + navQuery, navSort) }}
+    {{ if autoPrev }}{{ set prevLink = { label: autoPrev.nav_title || autoPrev.title, href: autoPrev.url } }}{{ /if }}
+  {{ /if }}
+  {{ if !nextLink }}
+    {{ set autoNext = nav.nextPage(url, "url^=/reference/ " + navQuery, navSort) }}
+    {{ if autoNext }}{{ set nextLink = { label: autoNext.nav_title || autoNext.title, href: autoNext.url } }}{{ /if }}
+  {{ /if }}
+{{ /if }}
+{{ if prevLink || nextLink }}
 <nav class="ns-nextprev" aria-label="Pagination">
-  {{ if prev }}
-    <a class="ns-nextprev__link ns-nextprev__link--prev" href="{{ prev.href |> url }}" rel="prev">
+  {{ if prevLink }}
+    <a class="ns-nextprev__link ns-nextprev__link--prev" href="{{ prevLink.href |> url }}" rel="prev">
       <span class="ns-nextprev__dir" aria-hidden="true">← Previous</span>
-      <span class="ns-nextprev__label">{{ prev.label }}</span>
+      <span class="ns-nextprev__label">{{ prevLink.label }}</span>
     </a>
   {{ /if }}
-  {{ if next }}
-    <a class="ns-nextprev__link ns-nextprev__link--next" href="{{ next.href |> url }}" rel="next">
+  {{ if nextLink }}
+    <a class="ns-nextprev__link ns-nextprev__link--next" href="{{ nextLink.href |> url }}" rel="next">
       <span class="ns-nextprev__dir" aria-hidden="true">Next →</span>
-      <span class="ns-nextprev__label">{{ next.label }}</span>
+      <span class="ns-nextprev__label">{{ nextLink.label }}</span>
     </a>
   {{ /if }}
 </nav>

docs/site/_config.ts

@@ -1,5 +1,7 @@
 import lume from "lume/mod.ts";
 import basePath from "lume/plugins/base_path.ts";
+import nav from "lume/plugins/nav.ts";
+import redirects from "lume/plugins/redirects.ts";
 import pagefind from "lume/plugins/pagefind.ts";
 import codeHighlight from "lume/plugins/code_highlight.ts";
 import anchor from "npm:markdown-it-anchor@9.2.0";
@@ -89,6 +91,15 @@ site.filter(
 // resolves without an in-template import). Throws on unknown key inside the build.
 site.data("resolveXref", resolveXref);
 
+// Multilevel sidebar (docs-v5 IA): nav.menu()/nav.breadcrumb() derive the tree
+// from page URLs; the sidebar lanes are curated in `_data.ts` `navLanes`.
+site.use(nav());
+
+// Moved-URL shims: pages declare `oldUrl` front matter and the plugin emits a
+// meta-refresh page at the old URL (GitHub Pages cannot 301). Registered before
+// base_path so the generated pages get base-prefixed hrefs like everything else.
+site.use(redirects());
+
 // Syntax highlighting for fenced code blocks (TD-6).
 site.use(codeHighlight({
   languages: {