jekyll-theme-zer0 1.24.0 → 1.25.0

data/_includes/navigation/local-graph.html

@@ -1,3 +1,4 @@
+{% comment %} Feature: ZER0-045 {% endcomment %}
 {%- comment -%}
   ===================================================================
   LOCAL GRAPH SIDEBAR — collapsible page-scoped graph
@@ -24,15 +25,9 @@
   Configurable depth: `local_graph_depth: 2` in page front matter (default 1).
   ===================================================================
 {%- endcomment -%}
-{%- assign _effective_sidebar = page.sidebar -%}
-{%- if _effective_sidebar == nil -%}
-  {%- if page.post_type == "featured" or page.post_type == "breaking" -%}
-    {%- assign _effective_sidebar = false -%}
-  {%- else -%}
-    {%- assign _effective_sidebar = true -%}
-  {%- endif -%}
-{%- endif -%}
-{%- if page.local_graph != false and _effective_sidebar != false -%}
+{%- comment -%} Shared visibility resolver — sets sidebar_enabled {%- endcomment -%}
+{%- include navigation/sidebar-config.html -%}
+{%- if page.local_graph != false and sidebar_enabled -%}
 {%- assign lg_depth = page.local_graph_depth | default: 1 -%}
 <aside class="offcanvas offcanvas-start obsidian-local-graph-panel"
        tabindex="-1"

data/_includes/navigation/navbar.html

@@ -1,3 +1,4 @@
+{% comment %} Features: ZER0-049, ZER0-055 {% endcomment %}
 <!-- 
     file: navbar.html
     path: /includes/navbar.html

data/_includes/navigation/sidebar-categories.html

@@ -1,32 +1,74 @@
-<!-- sidebar-categories.html -->
-{%- assign categories = include.categories | default: site.categories -%}
+{% comment %} Feature: ZER0-008 {% endcomment %}
+{%- comment -%}
+  Component:   sidebar-categories
+  Path:        _includes/navigation/sidebar-categories.html
+  Purpose:     "categories" / "tags" sidebar modes — collapsible taxonomy
+               groups with the posts filed under each term.
+  Params:      taxonomy (string, optional) — "categories" (default) | "tags"
+               categories (map, optional) — explicit term→posts map to render
+                 (back-compat; overrides the taxonomy lookup)
+               title (string, optional) — heading override
+               icon (string, optional) — Bootstrap Icons class override
+  Front matter (page.sidebar hash, all optional):
+               taxonomy — "categories" | "tags" (same as the param)
+               limit    — max posts listed per term (default: all)
+  Depends on:  site.categories / site.tags (posts only — Jekyll does not
+               index collection docs here), Bootstrap 5 collapse,
+               Bootstrap Icons, _sass/core/_sidebar-categories.scss
+  Notes:       Groups containing the current page start expanded. Each term
+               shows a post-count badge.
+{%- endcomment -%}
+{%- assign _type = include.taxonomy | default: page.sidebar.taxonomy | default: "categories" -%}
+{%- if _type == "tags" -%}
+  {%- assign _terms = site.tags -%}
+  {%- assign _heading = include.title | default: "Tags" -%}
+  {%- assign _heading_icon = include.icon | default: "bi-tags" -%}
+  {%- assign _id_prefix = "tag-" -%}
+{%- else -%}
+  {%- assign _terms = site.categories -%}
+  {%- assign _heading = include.title | default: "Categories" -%}
+  {%- assign _heading_icon = include.icon | default: "bi-folder2-open" -%}
+  {%- assign _id_prefix = "cat-" -%}
+{%- endif -%}
+{%- assign _terms = include.categories | default: _terms -%}
+{%- assign _terms = _terms | sort -%}
+{%- assign _limit = page.sidebar.limit -%}
 <div class="sidebar-categories nav-tree nav-tree--categories w-100">
   <h2 class="sidebar-categories-heading h6 text-uppercase text-body-secondary fw-semibold mb-3 d-flex align-items-center gap-2">
-    <i class="bi bi-folder2-open" aria-hidden="true"></i>
-    <span>Categories</span>
+    <i class="bi {{ _heading_icon }}" aria-hidden="true"></i>
+    <span>{{ _heading }}</span>
   </h2>
 
   <ul class="list-unstyled nav-tree-root mb-0">
-    {%- for category in categories -%}
-      {%- assign category_id = category[0] | slugify | prepend: "cat-" -%}
+    {%- for term in _terms -%}
+      {%- assign term_id = term[0] | slugify | prepend: _id_prefix -%}
+      {%- assign term_posts = term[1] -%}
+      {%- assign _active_here = term_posts | where: "url", page.url | size -%}
+      {%- if _active_here > 0 -%}
+        {%- assign _expanded = true -%}
+      {%- else -%}
+        {%- assign _expanded = false -%}
+      {%- endif -%}
       <li class="nav-tree-item sidebar-categories-group" data-depth="0">
-        <button class="btn btn-link nav-tree-toggle sidebar-categories-toggle w-100 d-flex align-items-center text-start collapsed"
+        <button class="btn btn-link nav-tree-toggle sidebar-categories-toggle w-100 d-flex align-items-center text-start{% unless _expanded %} collapsed{% endunless %}"
                 type="button"
                 data-bs-toggle="collapse"
-                data-bs-target="#{{ category_id }}-list"
-                aria-expanded="false"
-                aria-controls="{{ category_id }}-list">
+                data-bs-target="#{{ term_id }}-list"
+                aria-expanded="{{ _expanded }}"
+                aria-controls="{{ term_id }}-list">
           <i class="bi bi-folder sidebar-categories-toggle__icon" aria-hidden="true"></i>
-          <span class="sidebar-categories-toggle__label flex-grow-1">{{ category[0] }}</span>
+          <span class="sidebar-categories-toggle__label flex-grow-1">{{ term[0] }}</span>
+          <span class="badge text-bg-secondary bg-opacity-25 me-1">{{ term[1] | size }}</span>
           <i class="bi bi-chevron-down nav-tree-chevron sidebar-categories-toggle__chevron" aria-hidden="true"></i>
         </button>
 
-        <div class="collapse" id="{{ category_id }}-list">
+        <div class="collapse{% if _expanded %} show{% endif %}" id="{{ term_id }}-list">
           <ul class="list-unstyled nav-tree-children sidebar-categories-posts mb-0">
-            {%- for post in category[1] -%}
+            {%- for post in term_posts -%}
+              {%- if _limit and forloop.index0 >= _limit -%}{%- break -%}{%- endif -%}
               <li class="nav-tree-item" data-depth="1">
                 <a href="{{ post.url | relative_url }}"
-                   class="nav-tree-link sidebar-categories-link d-flex align-items-start rounded text-decoration-none{% if page.url == post.url %} active{% endif %}">
+                   class="nav-tree-link sidebar-categories-link d-flex align-items-start rounded text-decoration-none{% if page.url == post.url %} active{% endif %}"{% if page.url == post.url %} aria-current="page"{% endif %}>
                   <i class="bi bi-file-earmark-text sidebar-categories-link__icon" aria-hidden="true"></i>
                   <span class="sidebar-categories-link__text">{{ post.title }}</span>
                 </a>

data/_includes/navigation/sidebar-config.html

@@ -0,0 +1,115 @@
+{%- comment -%}
+  Component:   sidebar-config
+  Path:        _includes/navigation/sidebar-config.html
+  Purpose:     Resolve the effective left-sidebar configuration for the
+               current page. Jekyll `assign`s inside an include propagate to
+               the including template, so this is the single source of truth
+               shared by _layouts/default.html, _includes/core/header.html,
+               navigation/sidebar-left.html and navigation/unified-drawer.html
+               (previously each duplicated this logic and drifted).
+  Params:      none — reads page / collection / site state.
+  Sets (caller scope):
+               sidebar_enabled     — false when the page opts out entirely
+                                     (`sidebar: false`, or featured/breaking
+                                     post_type with no explicit setting)
+               sidebar_nav         — resolved concrete mode: "collection",
+                                     "categories", "tags", or the name of a
+                                     _data/navigation/*.yml file (nil = none)
+               sidebar_has_content — true only when sidebar_nav will actually
+                                     render items (gates the left column and
+                                     the mobile toggle)
+               sidebar_title       — heading text for the sidebar panel
+               sidebar_icon        — Bootstrap Icons class for the heading
+  Config precedence (most specific wins):
+               1. page.sidebar   (false | true | {nav, title, icon, ...})
+               2. `sidebar:` metadata on the page's collection (_config.yml
+                  `collections.<label>.sidebar.{nav,title,icon}`)
+               3. site.sidebar   ({nav, title, icon} in _config.yml)
+  Notes:       `nav: auto` picks the best mode for the page's collection —
+               a curated _data/navigation/<collection>.yml wins, then the
+               live "collection" folder tree, then post "categories".
+{%- endcomment -%}
+
+{%- comment -%} 1. Visibility: page.sidebar wins; featured/breaking posts default off {%- endcomment -%}
+{%- assign sidebar_enabled = true -%}
+{%- if page.sidebar == false -%}
+  {%- assign sidebar_enabled = false -%}
+{%- elsif page.sidebar == nil -%}
+  {%- if page.post_type == "featured" or page.post_type == "breaking" -%}
+    {%- assign sidebar_enabled = false -%}
+  {%- endif -%}
+{%- endif -%}
+
+{%- comment -%} 2. Collection-level sidebar metadata (optional) {%- endcomment -%}
+{%- assign sidebar_collection_cfg = nil -%}
+{%- if page.collection -%}
+  {%- assign _sidebar_coll = site.collections | where: "label", page.collection | first -%}
+  {%- if _sidebar_coll -%}
+    {%- assign sidebar_collection_cfg = _sidebar_coll.sidebar -%}
+  {%- endif -%}
+{%- endif -%}
+
+{%- comment -%} 3. Nav mode: page → collection metadata → site default {%- endcomment -%}
+{%- assign sidebar_nav = nil -%}
+{%- if sidebar_enabled -%}
+  {%- if page.sidebar.nav -%}
+    {%- assign sidebar_nav = page.sidebar.nav -%}
+  {%- elsif sidebar_collection_cfg.nav -%}
+    {%- assign sidebar_nav = sidebar_collection_cfg.nav -%}
+  {%- elsif site.sidebar.nav -%}
+    {%- assign sidebar_nav = site.sidebar.nav -%}
+  {%- endif -%}
+{%- endif -%}
+
+{%- comment -%} 4. "auto" → concrete mode based on the page's collection {%- endcomment -%}
+{%- if sidebar_nav == "auto" -%}
+  {%- assign sidebar_nav = nil -%}
+  {%- if page.collection -%}
+    {%- if site.data.navigation[page.collection] -%}
+      {%- assign sidebar_nav = page.collection -%}
+    {%- else -%}
+      {%- assign sidebar_nav = "collection" -%}
+    {%- endif -%}
+  {%- elsif site.categories.size > 0 -%}
+    {%- assign sidebar_nav = "categories" -%}
+  {%- endif -%}
+{%- endif -%}
+
+{%- comment -%} 5. Content gate — never reserve an empty left column {%- endcomment -%}
+{%- assign sidebar_has_content = false -%}
+{%- if sidebar_nav -%}
+  {%- case sidebar_nav -%}
+    {%- when "collection" -%}
+      {%- if page.sidebar.collection or page.collection -%}
+        {%- assign sidebar_has_content = true -%}
+      {%- endif -%}
+    {%- when "categories" -%}
+      {%- if site.categories.size > 0 -%}
+        {%- assign sidebar_has_content = true -%}
+      {%- endif -%}
+    {%- when "tags" -%}
+      {%- if site.tags.size > 0 -%}
+        {%- assign sidebar_has_content = true -%}
+      {%- endif -%}
+    {%- else -%}
+      {%- if site.data.navigation[sidebar_nav] -%}
+        {%- assign sidebar_has_content = true -%}
+      {%- endif -%}
+  {%- endcase -%}
+{%- endif -%}
+
+{%- comment -%} 6. Panel heading text + icon (page → collection → site → theme default) {%- endcomment -%}
+{%- assign sidebar_title = site.sidebar.title | default: "Browse docs" -%}
+{%- assign sidebar_icon = site.sidebar.icon | default: "bi-journal-bookmark" -%}
+{%- if sidebar_collection_cfg.title -%}
+  {%- assign sidebar_title = sidebar_collection_cfg.title -%}
+{%- endif -%}
+{%- if sidebar_collection_cfg.icon -%}
+  {%- assign sidebar_icon = sidebar_collection_cfg.icon -%}
+{%- endif -%}
+{%- if page.sidebar.title -%}
+  {%- assign sidebar_title = page.sidebar.title -%}
+{%- endif -%}
+{%- if page.sidebar.icon -%}
+  {%- assign sidebar_icon = page.sidebar.icon -%}
+{%- endif -%}

data/_includes/navigation/sidebar-folders.html

@@ -1,68 +1,174 @@
-<!--
-  ===================================================================
-  SIDEBAR FOLDERS - Collection Document Folder Structure
-  ===================================================================
-  
-  File: sidebar-folders.html
-  Path: _includes/navigation/sidebar-folders.html
-  Purpose: Display collection documents organized by folder structure
-  
-  Template Logic:
-  - Gets the current page's collection
-  - Sorts documents by path to maintain folder hierarchy
-  - Displays folder names and document links
-  - Uses Bootstrap list-group for styling with Bootstrap Icons
-  
-  Dependencies:
-  - page.collection: Current collection name from page front matter
-  - site.collections: Jekyll collections configuration
-  - Bootstrap 5 list-group component
-  - Bootstrap Icons for folder/file indicators
-  
-  Usage:
-  - Include in sidebar when page.sidebar.nav == "dynamic"
-  - Requires page to be part of a Jekyll collection
-  ===================================================================
--->
+{% comment %} Feature: ZER0-008 {% endcomment %}
+{%- comment -%}
+  Component:   sidebar-folders
+  Path:        _includes/navigation/sidebar-folders.html
+  Purpose:     "collection" sidebar mode — live folder tree of a collection's
+               documents, grouped by sub-folder into collapsible sections.
+               Zero-config: any collection gets a usable sidebar without a
+               curated _data/navigation/*.yml file.
+  Params:      collection (string, optional) — collection label to list
+                 (default: page.sidebar.collection, then page.collection)
+               sort (string, optional) — "path" | "title" | "date"
+                 (default: page.sidebar.sort, then "path")
+  Front matter (page.sidebar hash, all optional):
+               collection — list a different collection than the page's own
+               sort       — see above; "date" needs date/lastmod front matter
+               reverse    — true to reverse the sort (e.g. newest-first)
+               expand     — true to expand every folder group
+                            (default: only the group containing the page)
+  Per-document opt-out: set `sidebar_exclude: true` in a doc's front matter
+               to hide it from this tree.
+  Collection metadata (optional, in _config.yml `collections.<label>:`):
+               title — heading text (default: humanized label)
+               icon  — Bootstrap Icons class (default: bi-folder2-open)
+  Depends on:  site.collections, Bootstrap 5 collapse, Bootstrap Icons,
+               nav-tree styles (_sass/core/_nav-tree.scss)
+  Notes:       A folder's index.* doc becomes the folder link itself (link +
+               separate collapse toggle, mirroring nav-tree.html). Groups
+               containing the current page start expanded so the active link
+               is always visible. Folder names are humanized (hyphens/
+               underscores → spaces). Nested sub-folders render as their own
+               "parent / child" groups.
+{%- endcomment -%}
 
-{% assign root_folder = site.collections | where: "label", page.collection | first %}
+{%- assign _coll_label = include.collection | default: page.sidebar.collection | default: page.collection -%}
+{%- assign _coll = site.collections | where: "label", _coll_label | first -%}
 
-{% if root_folder %}
-  <h2 class="h5 mb-3 d-flex align-items-center">
-    <i class="bi bi-folder2-open me-2"></i>
-    {{ root_folder.label | capitalize }}
+{%- if _coll -%}
+  {%- assign _sort = include.sort | default: page.sidebar.sort | default: "path" -%}
+  {%- assign _docs = _coll.docs | where_exp: "d", "d.sidebar_exclude != true" -%}
+  {%- case _sort -%}
+    {%- when "title" -%}
+      {%- assign _docs = _docs | sort_natural: "title" -%}
+    {%- when "date" -%}
+      {%- assign _docs = _docs | sort: "date", "first" -%}
+    {%- else -%}
+      {%- assign _docs = _docs | sort: "path" -%}
+  {%- endcase -%}
+  {%- if page.sidebar.reverse == true -%}
+    {%- assign _docs = _docs | reverse -%}
+  {%- endif -%}
+
+  {%- comment -%}
+    Group documents by their directory relative to the collection folder.
+    Splitting on "_<label>/" works with and without a collections_dir prefix
+    in doc.path. Root-level docs land in the "" group.
+  {%- endcomment -%}
+  {%- capture _coll_prefix -%}_{{ _coll_label }}/{%- endcapture -%}
+  {%- assign _groups = _docs | group_by_exp: "d", "d.path | split: _coll_prefix | last | split: '/' | pop | join: '/'" | sort: "name" -%}
+
+  {%- assign _coll_title = _coll.title -%}
+  {%- unless _coll_title -%}
+    {%- assign _coll_title = _coll_label | replace: "-", " " | replace: "_", " " | capitalize -%}
+  {%- endunless -%}
+  {%- assign _coll_icon = _coll.icon | default: "bi-folder2-open" -%}
+  {%- assign _expand_all = page.sidebar.expand | default: false -%}
+
+<div class="sidebar-collection w-100">
+  <h2 class="sidebar-collection-heading h6 text-uppercase text-body-secondary fw-semibold mb-3 d-flex align-items-center gap-2">
+    <i class="bi {{ _coll_icon }}" aria-hidden="true"></i>
+    <span>{{ _coll_title }}</span>
   </h2>
-  
-  {% assign docs = root_folder.docs | sort: 'path' %}
-  {% assign prev_path = "" %}
-  
-  <ul class="list-group list-group-flush">
-    {% for doc in docs %}
-      {% assign current_path = doc.path | split: '/' | pop %}
-      
-      {% if current_path != prev_path %}
-        {% for folder in current_path %}
-          {% if forloop.index != 1 %}
-            <li class="folder list-group-item bg-body-tertiary fw-semibold d-flex align-items-center">
-              <i class="bi bi-folder2 me-2"></i>
-              {{ folder }}
-            </li>
-          {% endif %}
-        {% endfor %}
-        {% assign prev_path = current_path %}
-      {% endif %}
-      
-      <li class="file list-group-item list-group-item-action{% if page.url == doc.url %} active{% endif %}">
-        <a href="{{ doc.url | relative_url }}" class="text-decoration-none d-flex align-items-center">
-          <i class="bi bi-file-earmark-text me-2"></i>
-          {{ doc.title }}
-        </a>
-      </li>
-    {% endfor %}
+
+  <ul class="list-unstyled nav-tree-root mb-0">
+    {%- for group in _groups -%}
+      {%- if group.name == "" or group.name == nil -%}
+        {%- comment -%} Collection-root documents: flat depth-0 links {%- endcomment -%}
+        {%- for doc in group.items -%}
+          {%- assign _doc_title = doc.title -%}
+          {%- unless _doc_title -%}
+            {%- assign _doc_title = doc.path | split: "/" | last | split: "." | first | replace: "-", " " | replace: "_", " " | capitalize -%}
+          {%- endunless -%}
+          <li class="nav-tree-item" data-depth="0">
+            <a href="{{ doc.url | relative_url }}"
+               class="nav-tree-link d-flex align-items-start rounded py-1 px-2 text-decoration-none{% if page.url == doc.url %} active{% endif %}"{% if page.url == doc.url %} aria-current="page"{% endif %}>
+              <i class="bi bi-file-earmark-text me-2 flex-shrink-0" aria-hidden="true"></i>
+              <span>{{ _doc_title }}</span>
+            </a>
+          </li>
+        {%- endfor -%}
+      {%- else -%}
+        {%- assign _group_id = group.name | slugify | prepend: "sidebar-coll-" -%}
+        {%- assign _group_title = group.name | replace: "-", " " | replace: "_", " " | replace: "/", " / " | capitalize -%}
+        {%- assign _group_index = group.items | where_exp: "d", "d.path contains '/index.'" | first -%}
+        {%- assign _active_here = group.items | where: "url", page.url | size -%}
+        {%- if _expand_all or _active_here > 0 -%}
+          {%- assign _expanded = true -%}
+        {%- else -%}
+          {%- assign _expanded = false -%}
+        {%- endif -%}
+
+        {%- assign _group_size = group.items | size -%}
+        {%- if _group_index and _group_size == 1 -%}
+        {%- comment -%} Folder holds only its index doc — plain leaf, no toggle {%- endcomment -%}
+        <li class="nav-tree-item sidebar-collection-group" data-depth="0">
+          <a href="{{ _group_index.url | relative_url }}"
+             class="nav-tree-link d-flex align-items-start rounded py-1 px-2 text-decoration-none{% if page.url == _group_index.url %} active{% endif %}"{% if page.url == _group_index.url %} aria-current="page"{% endif %}>
+            <i class="bi bi-folder2 me-2 flex-shrink-0" aria-hidden="true"></i>
+            <span>{{ _group_title }}</span>
+          </a>
+        </li>
+        {%- else -%}
+        <li class="nav-tree-item sidebar-collection-group" data-depth="0">
+          {%- if _group_index -%}
+          {%- comment -%} Folder index doc → folder name links to it, chevron toggles {%- endcomment -%}
+          <div class="d-flex align-items-center">
+            <a href="{{ _group_index.url | relative_url }}"
+               class="nav-tree-link flex-grow-1 d-inline-flex align-items-center rounded py-1 px-2 text-decoration-none{% if page.url == _group_index.url %} active{% endif %}"{% if page.url == _group_index.url %} aria-current="page"{% endif %}>
+              <i class="bi bi-folder2 me-2" aria-hidden="true"></i>
+              <span>{{ _group_title }}</span>
+            </a>
+            <button class="btn btn-sm btn-link nav-tree-toggle p-1{% unless _expanded %} collapsed{% endunless %}"
+                    type="button"
+                    data-bs-toggle="collapse"
+                    data-bs-target="#{{ _group_id }}"
+                    aria-expanded="{{ _expanded }}"
+                    aria-controls="{{ _group_id }}"
+                    aria-label="Toggle {{ _group_title }} section">
+              <i class="bi bi-chevron-down nav-tree-chevron" aria-hidden="true"></i>
+            </button>
+          </div>
+          {%- else -%}
+          <button class="btn btn-link nav-tree-toggle w-100 d-flex align-items-center text-start py-1 px-2{% unless _expanded %} collapsed{% endunless %}"
+                  type="button"
+                  data-bs-toggle="collapse"
+                  data-bs-target="#{{ _group_id }}"
+                  aria-expanded="{{ _expanded }}"
+                  aria-controls="{{ _group_id }}">
+            <i class="bi bi-folder2 me-2" aria-hidden="true"></i>
+            <span class="flex-grow-1">{{ _group_title }}</span>
+            <i class="bi bi-chevron-down nav-tree-chevron" aria-hidden="true"></i>
+          </button>
+          {%- endif -%}
+
+          <div class="collapse{% if _expanded %} show{% endif %}" id="{{ _group_id }}">
+            <ul class="list-unstyled nav-tree-children mb-0">
+              {%- for doc in group.items -%}
+                {%- unless _group_index and doc.path == _group_index.path -%}
+                  {%- assign _doc_title = doc.title -%}
+                  {%- unless _doc_title -%}
+                    {%- assign _doc_title = doc.path | split: "/" | last | split: "." | first | replace: "-", " " | replace: "_", " " | capitalize -%}
+                  {%- endunless -%}
+                  <li class="nav-tree-item" data-depth="1">
+                    <a href="{{ doc.url | relative_url }}"
+                       class="nav-tree-link d-flex align-items-start rounded py-1 px-2 text-decoration-none{% if page.url == doc.url %} active{% endif %}"{% if page.url == doc.url %} aria-current="page"{% endif %}>
+                      <i class="bi bi-file-earmark-text me-2 flex-shrink-0" aria-hidden="true"></i>
+                      <span>{{ _doc_title }}</span>
+                    </a>
+                  </li>
+                {%- endunless -%}
+              {%- endfor -%}
+            </ul>
+          </div>
+        </li>
+        {%- endif -%}
+      {%- endif -%}
+    {%- endfor -%}
   </ul>
-{% else %}
-  <p class="text-muted small">
-    <i class="bi bi-info-circle me-1"></i>
+</div>
+{%- else -%}
+  <p class="text-body-secondary small mb-0">
+    <i class="bi bi-info-circle me-1" aria-hidden="true"></i>
     No collection found for this page.
   </p>
-{% endif %}
+{%- endif -%}

data/_includes/navigation/sidebar-left.html

@@ -1,32 +1,36 @@
-  <!--
+{% comment %} Feature: ZER0-008 {% endcomment %}
+<!--
   ===================================================================
   SIDEBAR LEFT - Dynamic Navigation Sidebar
   ===================================================================
-  
-  File: sidebar-left.html 
+
+  File: sidebar-left.html
   Path: _includes/navigation/sidebar-left.html
-  Purpose: Left sidebar navigation with three standardized content modes
-  
+  Purpose: Left sidebar panel (responsive offcanvas) around the resolved
+           sidebar navigation content
+
   Template Logic:
   - Responsive offcanvas sidebar for mobile devices
-  - Three navigation modes based on page.sidebar.nav:
-    * "auto": Auto-generated folder structure from collection documents
-    * "tree": YAML-defined hierarchical navigation from _data/navigation/
-    * "categories": Category-based navigation from site categories
-  
-  Dependencies:
-  - sidebar-folders.html: Dynamic folder structure generation (auto mode)
-  - sidebar-categories.html: Category-based navigation (categories mode)
-  - nav-tree.html: YAML-based hierarchical tree (tree mode)
-  - Bootstrap 5 offcanvas component
-  
-  Navigation Modes:
-  1. auto: Scans collection documents to build folder structure
-  2. tree: Uses predefined YAML navigation from _data/navigation/*.yml
-  3. categories: Groups content by Jekyll categories
+  - Mode resolution + rendering are delegated to shared includes:
+    * navigation/sidebar-config.html — resolves sidebar_nav / title / icon
+      from page.sidebar → collection `sidebar:` metadata → site.sidebar
+    * navigation/sidebar-nav.html — renders the resolved mode
+
+  Navigation modes (page.sidebar.nav — see sidebar-config.html):
+  - "auto": best mode for the page's collection (curated data file →
+    collection folder tree → post categories)
+  - "collection": live folder tree of the page's (or a named) collection
+  - "categories" / "tags": posts grouped by taxonomy term
+  - any other value: _data/navigation/<value>.yml rendered by nav-tree.html
+
+  Configuration:
+  - Heading text/icon: page.sidebar.title/icon → collection metadata →
+    site.sidebar.title/icon → "Browse docs"
   ===================================================================
 -->
 
+{% include navigation/sidebar-config.html %}
+
 <!-- ================================ -->
 <!-- SIDEBAR NAVIGATION CONTAINER   -->
 <!-- ================================ -->
@@ -45,7 +49,7 @@
   <!-- ========================== -->
   <!-- Mobile-only header with close button -->
   <div class="offcanvas-header">
-    <h2 class="offcanvas-title h5 mb-0" id="bdSidebarOffcanvasLabel">Browse docs</h2>
+    <h2 class="offcanvas-title h5 mb-0" id="bdSidebarOffcanvasLabel">{{ sidebar_title }}</h2>
     <div class="d-flex align-items-center gap-1">
       <button type="button"
               class="btn btn-sm btn-link text-body-secondary bd-sidebar-visibility-toggle d-lg-none px-2"
@@ -67,8 +71,8 @@
 
     <div class="bd-sidebar-desktop-header mb-3 d-none d-lg-flex align-items-center justify-content-between gap-2 w-100">
       <strong class="d-flex align-items-center mb-0">
-        <i class="bi bi-journal-bookmark me-2" aria-hidden="true"></i>
-        Browse docs
+        <i class="bi {{ sidebar_icon }} me-2" aria-hidden="true"></i>
+        {{ sidebar_title }}
       </strong>
       <button type="button"
               class="btn btn-sm btn-link text-body-secondary bd-sidebar-visibility-toggle d-none d-lg-inline-flex flex-shrink-0 px-1"
@@ -81,35 +85,8 @@
       </button>
     </div>
 
-    <!-- ========================== -->
-    <!-- AUTO MODE: Collection Docs -->
-    <!-- ========================== -->
-    <!-- Auto-generates folder structure from collection documents -->
-    {% if page.sidebar.nav == "auto" %}
-    <div class="list-group nav-tree" id="sidebar-content" data-nav-tree>
-      {% assign folders = site.pages | where_exp: "item", "item.path contains 'index.md'" | sort: 'path' %}
-      {% include navigation/sidebar-folders.html folders=folders %}
-    </div>
+    <!-- Resolved navigation content (see navigation/sidebar-nav.html) -->
+    {% include navigation/sidebar-nav.html id="sidebar-content" %}
 
-    <!-- ========================== -->
-    <!-- CATEGORIES MODE           -->
-    <!-- ========================== -->
-    <!-- Creates navigation from Jekyll post/page categories -->
-    {% elsif page.sidebar.nav == "categories" %}
-    <div class="nav-tree nav-tree--categories" id="sidebar-content" data-nav-tree>
-      {% assign categories = site.categories | sort %}
-      {% include navigation/sidebar-categories.html categories=categories %}
-    </div>
-    
-    <!-- ========================== -->
-    <!-- TREE MODE: YAML Navigation -->
-    <!-- ========================== -->
-    <!-- Uses predefined YAML navigation structure from _data files -->
-    {% elsif page.sidebar.nav %}
-    <nav class="w-100 nav-tree" data-nav-tree>
-      {% include navigation/nav-tree.html nav=page.sidebar.nav %}
-    </nav>
-    {% endif %}
-    
   </div>
 </div>

data/_includes/navigation/sidebar-nav.html

@@ -0,0 +1,30 @@
+{%- comment -%}
+  Component:   sidebar-nav
+  Path:        _includes/navigation/sidebar-nav.html
+  Purpose:     Render the resolved sidebar navigation content for the current
+               page. Expects navigation/sidebar-config.html to have been
+               included first in the same render context (it sets
+               `sidebar_nav`). Shared by navigation/sidebar-left.html and
+               navigation/unified-drawer.html so desktop sidebar and mobile
+               drawer can never drift apart.
+  Params:      id (string, optional) — id attribute for the content wrapper
+  Depends on:  navigation/sidebar-config.html (resolver),
+               navigation/sidebar-folders.html ("collection" mode),
+               navigation/sidebar-categories.html ("categories"/"tags" modes),
+               navigation/nav-tree.html (curated _data/navigation/*.yml modes)
+  Notes:       Renders nothing when sidebar_nav is nil or its data is empty —
+               callers gate the surrounding column on `sidebar_has_content`.
+{%- endcomment -%}
+{%- if sidebar_nav == "collection" -%}
+<div class="nav-tree"{% if include.id %} id="{{ include.id }}"{% endif %} data-nav-tree>
+  {% include navigation/sidebar-folders.html %}
+</div>
+{%- elsif sidebar_nav == "categories" or sidebar_nav == "tags" -%}
+<div class="nav-tree nav-tree--categories"{% if include.id %} id="{{ include.id }}"{% endif %} data-nav-tree>
+  {% include navigation/sidebar-categories.html taxonomy=sidebar_nav %}
+</div>
+{%- elsif sidebar_nav -%}
+<nav class="w-100 nav-tree"{% if include.id %} id="{{ include.id }}"{% endif %} data-nav-tree aria-label="Section navigation">
+  {% include navigation/nav-tree.html nav=sidebar_nav %}
+</nav>
+{%- endif -%}

data/_includes/navigation/sidebar-right.html

@@ -1,3 +1,4 @@
+{% comment %} Features: ZER0-008, ZER0-010 {% endcomment %}
 <!-- 
   file: sidebar-right.html 
   path: _includes/sidebar-right.html