Add sidebar layouts

layouts/partials/sidebar.html

@@ -0,0 +1,33 @@
+{{- /* Renders the sidebar navigation. Reads the sidebar key from page
+       params, looks up the matching data file in data/sidebars/, and
+       delegates tree rendering to sidebar_recursive.html. */ -}}
+{{- $sidebarKey := .Param "sidebar" | default "home_sidebar" -}}
+{{- $sidebarKeyText := strings.TrimSpace (printf "%v" $sidebarKey) -}}
+{{- $hasNoSidebar := or (eq $sidebarKeyText "nil") (eq $sidebarKeyText "<nil>") (eq $sidebarKeyText "false") -}}
+{{- if not $hasNoSidebar -}}
+{{- $sidebarData := index hugo.Data.sidebars $sidebarKey -}}
+{{- $entries := slice -}}
+{{- with $sidebarData.entries }}{{ $entries = . }}{{ end -}}
+{{- $firstEntry := index $entries 0 -}}
+
+{{- if $firstEntry -}}
+  {{- $product := $firstEntry.product | default $firstEntry.title | default "" -}}
+  {{- $version := $firstEntry.version | default "" -}}
+  <nav aria-label="{{ $product }}">
+    <ul id="mysidebar" class="sidebar-nav flex-column">
+      <li class="sidebarTitle">{{ strings.TrimSpace (printf "%s %s" $product $version) }}</li>
+      {{- range $entry := $entries }}
+        {{- range $folder := $entry.folders }}
+          {{- if partial "sidebar_is_web.html" $folder }}
+            {{ partial "sidebar_recursive.html" (dict "item" $folder "current" $ "level" 1 "parentID" "mysidebar") }}
+          {{- end }}
+        {{- end }}
+      {{- end }}
+    </ul>
+  </nav>
+{{- else -}}
+  {{- with $sidebarKey }}
+    <div class="sidebar-nav small text-muted" data-sidebar="{{ . }}">Sidebar source not found: {{ . }}</div>
+  {{- end }}
+{{- end -}}
+{{- end -}}

layouts/partials/sidebar_is_web.html

@@ -0,0 +1,5 @@
+{{- /* Returns truthy if the item should appear in web output
+       (i.e. its "output" field contains "web", defaulting to yes). */ -}}
+{{- $output := "web" -}}
+{{- with .output }}{{ $output = printf "%v" . }}{{ end -}}
+{{- if in $output "web" -}}true{{- end -}}

layouts/partials/sidebar_item_active.html

@@ -0,0 +1,43 @@
+{{- /* Recursively checks if any item in the given subtree matches the
+       current page. Returns truthy when a match is found, used to
+       expand parent collapse sections. Params: item, current. */ -}}
+{{- $item := .item -}}
+{{- $current := .current -}}
+{{- $active := false -}}
+
+{{- with $item.url }}
+  {{- if partial "sidebar_page_matches_url.html" (dict "page" $current "url" .) }}
+    {{- $active = true -}}
+  {{- end }}
+{{- end -}}
+
+{{- if not $active }}
+  {{- range $child := $item.folderitems }}
+    {{- if partial "sidebar_item_active.html" (dict "item" $child "current" $current) }}
+      {{- $active = true -}}
+    {{- end }}
+    {{- range $subfolder := $child.subfolders }}
+      {{- if partial "sidebar_item_active.html" (dict "item" $subfolder "current" $current) }}
+        {{- $active = true -}}
+      {{- end }}
+    {{- end }}
+  {{- end }}
+{{- end -}}
+
+{{- if not $active }}
+  {{- range $subfolder := $item.subfolders }}
+    {{- if partial "sidebar_item_active.html" (dict "item" $subfolder "current" $current) }}
+      {{- $active = true -}}
+    {{- end }}
+  {{- end }}
+{{- end -}}
+
+{{- if not $active }}
+  {{- range $child := $item.subfolderitems }}
+    {{- if partial "sidebar_item_active.html" (dict "item" $child "current" $current) }}
+      {{- $active = true -}}
+    {{- end }}
+  {{- end }}
+{{- end -}}
+
+{{- if $active -}}true{{- end -}}

layouts/partials/sidebar_page_matches_url.html

@@ -0,0 +1,20 @@
+{{- /* Checks if a page matches a target URL. Compares against the page's
+       RelPermalink, front-matter url, permalink, and aliases for a
+       reliable match regardless of how the URL was defined. */ -}}
+{{- $page := .page -}}
+{{- $target := partial "sidebar_url_clean.html" .url -}}
+{{- $matches := false -}}
+{{- if and $page $target }}
+  {{- $urls := slice -}}
+  {{- with $page.RelPermalink }}{{ $urls = $urls | append . }}{{ end -}}
+  {{- with $page.Params.url }}{{ $urls = $urls | append . }}{{ end -}}
+  {{- with $page.Params.permalink }}{{ $urls = $urls | append . }}{{ end -}}
+  {{- with $page.Params.aliases }}
+    {{- range . }}{{ $urls = $urls | append . }}{{ end -}}
+  {{- end -}}
+  {{- range $urls }}
+    {{- $clean := partial "sidebar_url_clean.html" . -}}
+    {{- if eq $clean $target }}{{ $matches = true }}{{ end -}}
+  {{- end }}
+{{- end -}}
+{{- if $matches -}}true{{- end -}}

layouts/partials/sidebar_recursive.html

@@ -0,0 +1,83 @@
+{{- /* Recursively renders a sidebar tree node.
+       Leaf items become plain nav-links; branch items become collapsible
+       sections (Bootstrap 5 collapse). Params: item, current (page context),
+       level (nesting depth, 1-based), parentID (BS collapse parent). */ -}}
+{{- $item := .item -}}
+{{- $current := .current -}}
+{{- $level := .level | default 1 -}}
+{{- $parentID := .parentID | default "mysidebar" -}}
+{{- $title := $item.title | default "" -}}
+{{- $url := $item.url | default "" -}}
+{{- $folderitems := $item.folderitems | default (slice) -}}
+{{- $subfolders := $item.subfolders | default (slice) -}}
+{{- $subfolderitems := $item.subfolderitems | default (slice) -}}
+{{- $isBranch := false -}}
+{{- if eq $level 1 }}
+  {{- if gt (len $folderitems) 0 }}{{ $isBranch = true }}{{ end -}}
+{{- else if eq $level 3 }}
+  {{- $isBranch = true -}}
+{{- end -}}
+{{- $isActive := partial "sidebar_item_active.html" (dict "item" $item "current" $current) -}}
+{{- $isCurrent := false -}}
+{{- if $url }}
+  {{- $isCurrent = partial "sidebar_page_matches_url.html" (dict "page" $current "url" $url) -}}
+{{- end -}}
+
+{{- if not $isBranch -}}
+  {{- $href := partial "sidebar_resolve_url.html" (dict "url" $url) -}}
+  <li class="nav-item">
+    <a class="nav-link {{ if $isCurrent }}active{{ end }}"
+       title="{{ $title }}" href="{{ $href }}">
+       {{ $title }}
+    </a>
+  </li>
+{{- else -}}
+  {{- $currentID := printf "sb-%d-%s" $level ($title | anchorize) -}}
+  {{- $nextLevel := add $level 1 -}}
+  <li class="nav-item">
+    <a class="nav-link {{ if $isActive }}active{{ else }}collapsed{{ end }}"
+       title="{{ $title }}"
+       data-bs-toggle="collapse" href="#{{ $currentID }}"
+       role="button"
+       aria-expanded="{{ if $isActive }}true{{ else }}false{{ end }}"
+       aria-controls="{{ $currentID }}">
+       {{ $title }}
+    </a>
+    <ul class="collapse {{ if $isActive }}show{{ end }} sidebar-nav flex-column list-unstyled mb-0"
+        id="{{ $currentID }}" data-bs-parent="#{{ $parentID }}">
+
+      {{- if $url }}
+        {{- $href := partial "sidebar_resolve_url.html" (dict "url" $url) -}}
+        <li class="nav-item">
+          <a class="nav-link {{ if $isCurrent }}active{{ end }}"
+             title="{{ $title }}" href="{{ $href }}">
+             {{ $title }} Overview
+          </a>
+        </li>
+      {{- end }}
+
+      {{- range $child := $folderitems }}
+        {{- if partial "sidebar_is_web.html" $child }}
+          {{ partial "sidebar_recursive.html" (dict "item" $child "current" $current "level" $nextLevel "parentID" $currentID) }}
+          {{- range $subfolder := $child.subfolders }}
+            {{- if partial "sidebar_is_web.html" $subfolder }}
+              {{ partial "sidebar_recursive.html" (dict "item" $subfolder "current" $current "level" 3 "parentID" $currentID) }}
+            {{- end }}
+          {{- end }}
+        {{- end }}
+      {{- end }}
+
+      {{- range $subfolder := $subfolders }}
+        {{- if partial "sidebar_is_web.html" $subfolder }}
+          {{ partial "sidebar_recursive.html" (dict "item" $subfolder "current" $current "level" $nextLevel "parentID" $currentID) }}
+        {{- end }}
+      {{- end }}
+
+      {{- range $child := $subfolderitems }}
+        {{- if partial "sidebar_is_web.html" $child }}
+          {{ partial "sidebar_recursive.html" (dict "item" $child "current" $current "level" $nextLevel "parentID" $currentID) }}
+        {{- end }}
+      {{- end }}
+    </ul>
+  </li>
+{{- end -}}

layouts/partials/sidebar_resolve_url.html

@@ -0,0 +1,11 @@
+{{- /* Resolves a sidebar URL for use in href attributes. External URLs
+       (http, https, mailto, #) are returned as-is; internal paths
+       are passed through relURL. */ -}}
+{{- $rawURL := .url | default "" -}}
+{{- $isExternal := or (hasPrefix $rawURL "http://") (or (hasPrefix $rawURL "https://") (or (hasPrefix $rawURL "mailto:") (hasPrefix $rawURL "#"))) -}}
+
+{{- if $isExternal -}}
+  {{- $rawURL -}}
+{{- else -}}
+  {{- $rawURL | relURL -}}
+{{- end -}}

layouts/partials/sidebar_url_clean.html

@@ -0,0 +1,8 @@
+{{- /* Normalises a URL for comparison: trims whitespace and strips
+       leading/trailing slashes so "docs/foo/" matches "docs/foo". */ -}}
+{{- $url := "" -}}
+{{- with . }}{{ $url = printf "%v" . }}{{ end -}}
+{{- $url = strings.TrimSpace $url -}}
+{{- $url = strings.TrimPrefix "/" $url -}}
+{{- $url = strings.TrimSuffix "/" $url -}}
+{{- $url -}}