jekyll-theme-zer0 1.29.0 → 1.30.0

data/_includes/core/footer.html

@@ -1,5 +1,5 @@
 {% comment %} Feature: ZER0-046 {% endcomment %}
-<!--
+{% comment %}
   ===================================================================
   FOOTER - Comprehensive Site Footer with Branding & Navigation
   ===================================================================
@@ -33,12 +33,12 @@
   - Guard optional fields (address/phone/email) to avoid empty output
   - Use relative_url for internal links to respect baseurl
   ===================================================================
--->
+{% endcomment %}
 
 {%- include core/i18n.html lang=include.lang -%}
 <footer class="bd-footer border-top" role="contentinfo">
   {% assign footer_page_urls = site.html_pages | map: "url" | join: "|" | prepend: "|" | append: "|" %}
-  <!-- Powered by Row -->
+  {% comment %} Powered by Row {% endcomment %}
   <div class="container-xl footer-powered-by">
     <p class="footer-powered-by-copyright text-center mb-0">
       &copy; {{ site.time | date: "%Y" }} {{ site.name | default: site.title }}
@@ -110,12 +110,12 @@
     </div>
   </div>
 
-  <!-- Branding and Navigation Block — full-width dark background -->
+  {% comment %} Branding and Navigation Block — full-width dark background {% endcomment %}
   <div class="bg-dark text-light footer-dark-block">
     <div class="container-xl">
-        <!-- Top: Site info + Quick Links + Social -->
+        {% comment %} Top: Site info + Quick Links + Social {% endcomment %}
         <div class="row mb-3 mb-lg-4 g-2 g-lg-3 footer-nav-columns justify-content-center">
-          <!-- Site Info -->
+          {% comment %} Site Info {% endcomment %}
           <div class="col-12 col-md-3 col-lg-3 mb-2 mb-lg-3 order-0 order-md-1 order-lg-1">
             <h2 class="footer-section-title text-uppercase h6 mb-0">{{ site.title }}</h2>
             {% if site.address %}<p class="mb-1">{{ site.address }}</p>{% endif %}
@@ -123,12 +123,12 @@
             {% if site.email %}<p class="mb-0"><a href="mailto:{{ site.email }}" class="text-light text-decoration-none">{{ site.email }}</a></p>{% endif %}
           </div>
 
-          <!-- Quick Links
+          {% comment %} Quick Links
                Resolution order:
                  1. site.footer_quick_links  (array of {label, url}) — explicit override
                  2. Auto-detection: only render links whose target pages
                     actually exist in the build. Prevents 404s on bare-minimum
-                    sites that haven't created /about/, /services/, etc. -->
+                    sites that haven't created /about/, /services/, etc. {% endcomment %}
           <div class="col-6 col-md-3 col-lg-3 mb-2 mb-lg-3 order-2 order-md-2 order-lg-2">
             <h2 class="footer-section-title text-uppercase h6 mb-0">Quick Links</h2>
             <ul class="list-unstyled" aria-label="Footer quick links">
@@ -171,7 +171,7 @@
             </ul>
           </div>
 
-          <!-- Latest Posts (dynamic) -->
+          {% comment %} Latest Posts (dynamic) {% endcomment %}
           {% assign posts_count = site.posts | size %}
           {% if posts_count and posts_count > 0 %}
           <div class="col-12 col-md-3 col-lg-3 mb-2 mb-lg-3 order-4 order-md-3 order-lg-3">
@@ -186,7 +186,7 @@
           </div>
           {% endif %}
 
-          <!-- Social & RSS -->
+          {% comment %} Social & RSS {% endcomment %}
           <div class="col-6 col-md-3 col-lg-3 mb-2 mb-lg-3 order-3 order-md-4 order-lg-4">
             <h2 class="footer-section-title text-uppercase h6 mb-0">Follow Us</h2>
             <ul class="list-inline mb-0" aria-label="Social links">
@@ -194,7 +194,17 @@
                 {% if link.url %}
                   <li class="list-inline-item">
                     {% capture link_icon_classes %}{{ site.default_icon }} {{ link.icon | default: "bi-link-45deg" }}{% endcapture %}
-                    <a href="{{ link.url }}" rel="nofollow" class="text-light text-decoration-none">
+                    {%- comment -%}
+                      aria-label is load-bearing below the md breakpoint (issue
+                      #435): the icon is aria-hidden and the label span is
+                      d-none there, so without it the link had NO accessible
+                      name at all on mobile — a screen reader announced bare
+                      "link". It matches the visible text exactly, so the
+                      accessible name still contains the visible label at md+
+                      (WCAG 2.5.3 Label in Name).
+                    {%- endcomment -%}
+                    <a href="{{ link.url }}" rel="nofollow" class="text-light text-decoration-none"
+                       aria-label="{{ link.label }}">
                       <i class="{{ link_icon_classes }}" aria-hidden="true"></i>
                       <span class="d-none d-md-inline">{{ link.label }}</span>
                     </a>
@@ -202,16 +212,19 @@
                 {% endif %}
               {% endfor %}
               <li class="list-inline-item">
-                <a class="text-light text-decoration-none" href="{{ '/feed.xml' | relative_url }}">
+                {%- comment -%} Same as the social links above (#435). {%- endcomment -%}
+                {%- assign _feed_label = ui.feed_label | default: "Feed" -%}
+                <a class="text-light text-decoration-none" href="{{ '/feed.xml' | relative_url }}"
+                   aria-label="{{ _feed_label }}">
                   <i class="{{ site.default_icon }} bi-rss" aria-hidden="true"></i>
-                  <span class="d-none d-md-inline">{{ ui.feed_label | default: "Feed" }}</span>
+                  <span class="d-none d-md-inline">{{ _feed_label }}</span>
                 </a>
               </li>
             </ul>
           </div>
         </div>
 
-        <!-- Middle: Subscribe + Policies -->
+        {% comment %} Middle: Subscribe + Policies {% endcomment %}
         <div class="row mb-3 mb-lg-4 align-items-center justify-content-center g-2 footer-subscribe-row">
           <div class="col-12 col-md-8 col-lg-8">
             <form class="row g-2 footer-subscribe-form" aria-label="Newsletter signup" onsubmit="return false;">
@@ -249,7 +262,7 @@
           </div>
         </div>
 
-      <!-- Bottom: Copyright -->
+      {% comment %} Bottom: Copyright {% endcomment %}
       <div class="text-center">
         <p class="mb-0">&copy; {{ site.time | date: "%Y" }} {{ site.title | default: site.name }}. All Rights Reserved.</p>
       </div>
@@ -265,9 +278,9 @@
     immediately after </footer> is visually identical to nesting them inside.
   {%- endcomment -%}
 
-  <!-- Back to Top Button (controlled by assets/js/back-to-top.js) -->
-  <!-- Positioning/stacking handled by _sass/components/_back-to-top.scss
-       via the FAB tokens (bottom-up: back-to-top → chat toggle → TOC FAB) -->
+  {% comment %} Back to Top Button (controlled by assets/js/back-to-top.js) {% endcomment %}
+  {% comment %} Positioning/stacking handled by _sass/components/_back-to-top.scss
+       via the FAB tokens (bottom-up: back-to-top → chat toggle → TOC FAB) {% endcomment %}
   <a
     id="backToTopBtn"
     href="#"

data/_includes/core/head.html

@@ -1,5 +1,5 @@
 {% comment %} Feature: ZER0-001 {% endcomment %}
-<!--
+{% comment %}
   ===================================================================
   HEAD - HTML Document Head Section
   ===================================================================
@@ -26,23 +26,23 @@
   - MathJax loaded asynchronously to prevent render blocking
   - Nanobar provides visual loading feedback (see components/nanobar.html)
   ===================================================================
--->
+{% endcomment %}
 
-<!-- ================================ -->
-<!-- ANALYTICS AND TRACKING          -->
-<!-- ================================ -->
-<!-- Google Tag Manager - Must be in head section for proper tracking -->
-<!-- Only load in production builds (JEKYLL_ENV=production); the include also guards against dev hostnames -->
+{% comment %} ================================ {% endcomment %}
+{% comment %} ANALYTICS AND TRACKING          {% endcomment %}
+{% comment %} ================================ {% endcomment %}
+{% comment %} Google Tag Manager - Must be in head section for proper tracking {% endcomment %}
+{% comment %} Only load in production builds (JEKYLL_ENV=production); the include also guards against dev hostnames {% endcomment %}
 {% if jekyll.environment == "production" %}{% include analytics/google-tag-manager-head.html %}{% endif %}
 
-<!-- Page-feedback: early console/error capture — must run before the theme
-     scripts below so a report can include the logs that led up to it. -->
+{% comment %} Page-feedback: early console/error capture — must run before the theme
+     scripts below so a report can include the logs that led up to it. {% endcomment %}
 {% include core/console-capture.html %}
 
-<!-- ================================ -->
-<!-- JAVASCRIPT LIBRARIES            -->
-<!-- ================================ -->
-<!-- Custom theme JavaScript - Deferred for performance -->
+{% comment %} ================================ {% endcomment %}
+{% comment %} JAVASCRIPT LIBRARIES            {% endcomment %}
+{% comment %} ================================ {% endcomment %}
+{% comment %} Custom theme JavaScript - Deferred for performance {% endcomment %}
 <script defer src="{{ '/assets/js/auto-hide-nav.js' | relative_url }}"></script>
 <script defer src="{{ '/assets/js/back-to-top.js' | relative_url }}"></script>
 <script defer src="{{ '/assets/js/halfmoon.js' | relative_url }}"></script>
@@ -51,34 +51,34 @@
 <script defer src="{{ '/assets/js/table-copy.js' | relative_url }}"></script>
 <script defer src="{{ '/assets/js/ui-enhancements.js' | relative_url }}"></script>
 
-<!-- Page-view counter — injects its config and loads assets/js/page-views.js.
+{% comment %} Page-view counter — injects its config and loads assets/js/page-views.js.
      Renders nothing on its own; components/page-views.html places the badge.
-     Gated on site.page_views.enabled inside the include. -->
+     Gated on site.page_views.enabled inside the include. {% endcomment %}
 {% include components/page-views-init.html %}
 
-<!-- ================================ -->
-<!-- THIRD PARTY INTEGRATIONS        -->
-<!-- ================================ -->
+{% comment %} ================================ {% endcomment %}
+{% comment %} THIRD PARTY INTEGRATIONS        {% endcomment %}
+{% comment %} ================================ {% endcomment %}
 
-<!-- Recipe scaling & unit conversion - Only on pages that render recipe
+{% comment %} Recipe scaling & unit conversion - Only on pages that render recipe
      quantities: the `recipe` layout, or any page that opts in with
-     `recipe_tools: true` (e.g. a post embedding components/recipe-*.html). -->
+     `recipe_tools: true` (e.g. a post embedding components/recipe-*.html). {% endcomment %}
 {% if page.layout == "recipe" or page.recipe_tools %}
 <script defer src="{{ '/assets/js/recipe-scaler.js' | relative_url }}"></script>
 {% endif %}
 
-<!-- Mermaid Diagrams - Conditional loading based on page front matter -->
+{% comment %} Mermaid Diagrams - Conditional loading based on page front matter {% endcomment %}
 {% if page.mermaid %}
   {% include components/mermaid.html %}
 {% endif %}
 
-<!-- Nano Progress Bar - Visual loading indicator (config-driven) — page-invariant, cached. -->
+{% comment %} Nano Progress Bar - Visual loading indicator (config-driven) — page-invariant, cached. {% endcomment %}
 {% include_cached components/nanobar.html %}
 
-<!-- MathJax - Conditional loading based on page front matter (like Mermaid) -->
+{% comment %} MathJax - Conditional loading based on page front matter (like Mermaid) {% endcomment %}
 {% if page.mathjax %}
-<!-- MathJax 3 configuration — must appear before the script tag.
-     Enables $...$ inline math (off by default in MathJax 3). -->
+{% comment %} MathJax 3 configuration — must appear before the script tag.
+     Enables $...$ inline math (off by default in MathJax 3). {% endcomment %}
 <script>
 window.MathJax = {
   tex: {
@@ -91,33 +91,45 @@ window.MathJax = {
 <script id="MathJax-script" async src="{{ '/assets/vendor/mathjax/es5/tex-mml-chtml.js' | relative_url }}"></script>
 {% endif %}
 
-<!-- ================================ -->
-<!-- HTML DOCUMENT META DATA         -->
-<!-- ================================ -->
-<!-- Essential meta tags for proper document rendering and mobile support -->
-<meta charset="utf-8">
+{% comment %} ================================ {% endcomment %}
+{% comment %} HTML DOCUMENT META DATA         {% endcomment %}
+{% comment %} ================================ {% endcomment %}
+{%- comment -%} NOTE: the charset meta is NOT here — it lives at the very top
+     of _layouts/root.html so it lands inside the spec's 1024-byte window
+     (issue #372). Do not re-add it here. {%- endcomment -%}
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
 
-<!-- Favicon + browser identity (config-driven via `favicon:`; explicit
-     /favicon.ico fallback so baseurl deployments resolve) — page-invariant, cached. -->
+{% comment %} Favicon + browser identity (config-driven via `favicon:`; explicit
+     /favicon.ico fallback so baseurl deployments resolve) — page-invariant, cached. {% endcomment %}
 {% include_cached core/favicon.html %}
 
-<!-- ================================ -->
-<!-- SEO SUPPLEMENT                  -->
-<!-- ================================ -->
-<!-- Additional SEO tags not covered by jekyll-seo-tag plugin ( in root.html).
-     Outputs custom og:image with assets_prefix normalisation and non-Google site verification. -->
+{%- comment -%} Feed autodiscovery. jekyll-feed generates /feed.xml but emits
+     no link element unless feed_meta is called, so the feed was undiscoverable
+     to readers and crawlers even though the footer links it (issue #371).
+     Written out by hand rather than via feed_meta so the theme does not
+     hard-fail with "Unknown tag" on a consumer site that has not enabled the
+     plugin; the path matches the footer's own /feed.xml link. {%- endcomment -%}
+{%- assign _feed_path = site.feed.path | default: 'feed.xml' -%}
+<link rel="alternate" type="application/atom+xml"
+      title="{{ site.title | default: site.name | escape }}"
+      href="{{ _feed_path | relative_url }}">
+
+{% comment %} ================================ {% endcomment %}
+{% comment %} SEO SUPPLEMENT                  {% endcomment %}
+{% comment %} ================================ {% endcomment %}
+{% comment %} Additional SEO tags not covered by jekyll-seo-tag plugin ( in root.html).
+     Outputs custom og:image with assets_prefix normalisation and non-Google site verification. {% endcomment %}
 {% include content/seo.html %}
 
-<!-- hreflang alternates for machine-generated translations (no-op when the
-     page has none) — see _data/i18n/manifest.yml + scripts/translate.rb -->
+{% comment %} hreflang alternates for machine-generated translations (no-op when the
+     page has none) — see _data/i18n/manifest.yml + scripts/translate.rb {% endcomment %}
 {% include core/hreflang.html %}
 
-<!-- ========================== -->
-<!-- STRUCTURED DATA MARKUP    -->
-<!-- ========================== -->
-<!-- Enhanced meta data for rich snippets and social media -->
+{% comment %} ========================== {% endcomment %}
+{% comment %} STRUCTURED DATA MARKUP    {% endcomment %}
+{% comment %} ========================== {% endcomment %}
+{% comment %} Enhanced meta data for rich snippets and social media {% endcomment %}
 {% if page.title %}
     <meta itemprop="headline" content="{{ page.title | markdownify | strip_html | strip_newlines | escape_once }}">
 {% endif %}
@@ -135,84 +147,84 @@ window.MathJax = {
     <meta itemprop="dateModified" content="{{ page.lastmod | date_to_xmlschema }}">
 {% endif %}
 
-<!-- JSON-LD SoftwareApplication schema (homepage only) -->
+{% comment %} JSON-LD SoftwareApplication schema (homepage only) {% endcomment %}
 {% include content/jsonld-software.html %}
 
-<!-- JSON-LD FAQ schema (pages with faq_items front matter) -->
+{% comment %} JSON-LD FAQ schema (pages with faq_items front matter) {% endcomment %}
 {% include content/jsonld-faq.html %}
 
-<!-- ========================== -->
-<!-- ANALYTICS INTEGRATION     -->
-<!-- ========================== -->
-<!-- Google Analytics tracking - Configured in _config.yml -->
-<!-- Only load in production AND when an ID is configured; the include also guards against dev hostnames -->
+{% comment %} ========================== {% endcomment %}
+{% comment %} ANALYTICS INTEGRATION     {% endcomment %}
+{% comment %} ========================== {% endcomment %}
+{% comment %} Google Analytics tracking - Configured in _config.yml {% endcomment %}
+{% comment %} Only load in production AND when an ID is configured; the include also guards against dev hostnames {% endcomment %}
 {% if jekyll.environment == "production" and site.google_analytics %}{% include analytics/google-analytics.html %}{% endif %}
 
-<!-- PostHog analytics - Configured via the `posthog:` block in _config.yml -->
-<!-- Only load in production AND when explicitly enabled; the include itself also respects Do Not Track -->
+{% comment %} PostHog analytics - Configured via the `posthog:` block in _config.yml {% endcomment %}
+{% comment %} Only load in production AND when explicitly enabled; the include itself also respects Do Not Track {% endcomment %}
 {% if jekyll.environment == "production" and site.posthog.enabled %}{% include analytics/posthog.html %}{% endif %}
 
 
-<!-- ================================ -->
-<!-- CSS FRAMEWORKS AND LIBRARIES   -->
-<!-- ================================ -->
+{% comment %} ================================ {% endcomment %}
+{% comment %} CSS FRAMEWORKS AND LIBRARIES   {% endcomment %}
+{% comment %} ================================ {% endcomment %}
 
-<!-- ========================== -->
-<!-- COLOR MODE INIT (FOUC FIX) -->
-<!-- ========================== -->
-<!-- Must run BEFORE Bootstrap CSS so the correct data-bs-theme is applied
+{% comment %} ========================== {% endcomment %}
+{% comment %} COLOR MODE INIT (FOUC FIX) {% endcomment %}
+{% comment %} ========================== {% endcomment %}
+{% comment %} Must run BEFORE Bootstrap CSS so the correct data-bs-theme is applied
      when [data-bs-theme=dark/light] selectors are first evaluated.
      Reads site.color_mode_default (via data-color-mode-default attr on <html>)
-     and falls back to localStorage["theme"] for the user's explicit preference. -->
+     and falls back to localStorage["theme"] for the user's explicit preference. {% endcomment %}
 {% include core/color-mode-init.html %}
 
-<!-- ========================== -->
-<!-- BOOTSTRAP 5 FRAMEWORK     -->
-<!-- ========================== -->
-<!-- Bootstrap 5.3.3 - bundled locally (GitHub Pages–safe; refresh via scripts/vendor-install.sh) -->
+{% comment %} ========================== {% endcomment %}
+{% comment %} BOOTSTRAP 5 FRAMEWORK     {% endcomment %}
+{% comment %} ========================== {% endcomment %}
+{% comment %} Bootstrap 5.3.3 - bundled locally (GitHub Pages–safe; refresh via scripts/vendor-install.sh) {% endcomment %}
 <link href="{{ '/assets/vendor/bootstrap/css/bootstrap.min.css' | relative_url }}" rel="stylesheet">
 
-<!-- ========================== -->
-<!-- ICON LIBRARIES             -->
-<!-- ========================== -->
-<!-- Bootstrap Icons (bundled with theme; fonts use relative paths in CSS) -->
+{% comment %} ========================== {% endcomment %}
+{% comment %} ICON LIBRARIES             {% endcomment %}
+{% comment %} ========================== {% endcomment %}
+{% comment %} Bootstrap Icons (bundled with theme; fonts use relative paths in CSS) {% endcomment %}
 <link rel="stylesheet" href="{{ '/assets/vendor/bootstrap-icons/font/bootstrap-icons.css' | relative_url }}">
 
-<!-- ========================== -->
-<!-- CUSTOM THEME STYLES       -->
-<!-- ========================== -->
-<!-- Primary theme stylesheet - Core styling and layout (SCSS pipeline) -->
+{% comment %} ========================== {% endcomment %}
+{% comment %} CUSTOM THEME STYLES       {% endcomment %}
+{% comment %} ========================== {% endcomment %}
+{% comment %} Primary theme stylesheet - Core styling and layout (SCSS pipeline) {% endcomment %}
 <link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}">
 
-<!-- ========================== -->
-<!-- DESIGN TOKEN OVERRIDES     -->
-<!-- ========================== -->
-<!-- Inline <style> block emitted AFTER main.css so site-config `theme_color` keys
-     and any per-user Appearance overrides win over compiled defaults. -->
+{% comment %} ========================== {% endcomment %}
+{% comment %} DESIGN TOKEN OVERRIDES     {% endcomment %}
+{% comment %} ========================== {% endcomment %}
+{% comment %} Inline <style> block emitted AFTER main.css so site-config `theme_color` keys
+     and any per-user Appearance overrides win over compiled defaults. {% endcomment %}
 {% include core/tokens-inline.html %}
 
-<!-- Optional fork overrides: opt-in via `site.user_overrides: true` in _config.yml.
-     Loaded LAST so consumer rules win over both main.css and tokens-inline. -->
+{% comment %} Optional fork overrides: opt-in via `site.user_overrides: true` in _config.yml.
+     Loaded LAST so consumer rules win over both main.css and tokens-inline. {% endcomment %}
 {% if site.user_overrides %}
 <link rel="stylesheet" href="{{ '/assets/css/user-overrides.css' | relative_url }}">
 {% endif %}
 
-<!-- Statistics page specific styles -->
+{% comment %} Statistics page specific styles {% endcomment %}
 {% if page.layout == 'stats' or page.permalink == '/about/stats/' %}
 <link rel="stylesheet" href="{{ '/assets/css/stats.css' | relative_url }}">
 {% endif %}
 
-<!-- Consumer hook: end of <head>. Inject JSON-LD, font preloads, verification
+{% comment %} Consumer hook: end of <head>. Inject JSON-LD, font preloads, verification
      tags, or extra meta by shadowing _includes/custom/head.html in your site —
-     no fork of this file needed. The theme ships the stub empty. -->
+     no fork of this file needed. The theme ships the stub empty. {% endcomment %}
 {% include custom/head.html %}
 
-<!-- ========================== -->
-<!-- EXPERIMENTAL FRAMEWORKS   -->
-<!-- ========================== -->
-<!-- Tailwind CSS - Currently disabled, enable for utility-first styling -->
-<!-- <script src="https://cdn.tailwindcss.com"></script> -->
+{% comment %} ========================== {% endcomment %}
+{% comment %} EXPERIMENTAL FRAMEWORKS   {% endcomment %}
+{% comment %} ========================== {% endcomment %}
+{% comment %} Tailwind CSS - Currently disabled, enable for utility-first styling {% endcomment %}
+{% comment %} <script src="https://cdn.tailwindcss.com"></script> {% endcomment %}
 
-<!-- Docs CSS - Alternative stylesheet, currently disabled due to scroll spy issues -->
-<!-- TODO: Replace with compiled Sass when scroll spy functionality is fixed -->
-<!-- Optional docs.css link removed; use _sass/core/_docs-layout.scss → main.css -->
+{% comment %} Docs CSS - Alternative stylesheet, currently disabled due to scroll spy issues {% endcomment %}
+{% comment %} TODO: Replace with compiled Sass when scroll spy functionality is fixed {% endcomment %}
+{% comment %} Optional docs.css link removed; use _sass/core/_docs-layout.scss → main.css {% endcomment %}

data/_includes/core/header.html

@@ -1,5 +1,5 @@
 {% comment %} Feature: ZER0-011 {% endcomment %}
-<!--
+{% comment %}
   ===================================================================
   HEADER - Main Navigation and Site Header
   ===================================================================
@@ -36,48 +36,67 @@
   - When `position: navbar`, the bar mounts inside `#top-progress-target` below
   - Otherwise it floats fixed to the viewport (top or bottom)
   ===================================================================
--->
+{% endcomment %}
 
-<!-- ================================ -->
-<!-- SKIP TO CONTENT LINK            -->
-<!-- ================================ -->
-<!-- UI strings resolve per page language (core/i18n.html sets `ui`) -->
+{% comment %} ================================ {% endcomment %}
+{% comment %} SKIP TO CONTENT LINK            {% endcomment %}
+{% comment %} ================================ {% endcomment %}
+{% comment %} UI strings resolve per page language (core/i18n.html sets `ui`) {% endcomment %}
 {%- include core/i18n.html -%}
-<!-- Accessibility: allows keyboard users to skip navigation -->
+{% comment %} Accessibility: allows keyboard users to skip navigation {% endcomment %}
 <a href="#main-content" class="visually-hidden-focusable position-absolute top-0 start-0 z-3 m-3 btn btn-primary">
   {{ ui.skip_main_content | default: "Skip to main content" }}
 </a>
 
 <header id="navbar" class="container-fluid text-center fixed-top" role="banner">
 
-    <!-- ================================ -->
-    <!-- TOP NAVIGATION BAR              -->
-    <!-- ================================ -->
+    {% comment %} ================================ {% endcomment %}
+    {% comment %} TOP NAVIGATION BAR              {% endcomment %}
+    {% comment %} ================================ {% endcomment %}
     <div class="navbar navbar-expand-lg bg-body-tertiary flex-nowrap w-100 bottom-shadow">
 
-        <!-- ========================== -->
-        <!-- MAIN NAVIGATION CONTAINER -->
-        <!-- ========================== -->
+        {% comment %} ========================== {% endcomment %}
+        {% comment %} MAIN NAVIGATION CONTAINER {% endcomment %}
+        {% comment %} ========================== {% endcomment %}
         <nav class="container-fluid order-2 order-lg-1 d-flex align-items-center gap-1 flex-nowrap navbar-main w-100" aria-label="Primary navigation">
 
-            <!-- Leading cluster: sidebar toggle + brand + titles (grid column 1 on lg+) -->
+            {% comment %} Leading cluster: sidebar toggle + brand + titles (grid column 1 on lg+) {% endcomment %}
             <div class="navbar-main-start d-flex align-items-center gap-1 gap-lg-2 min-w-0 flex-shrink-1 flex-grow-1">
 
-            <!-- ========================== -->
-            <!-- MOBILE MENU CONTROLS      -->
-            <!-- ========================== -->
+            {% comment %} ========================== {% endcomment %}
+            {% comment %} MOBILE MENU CONTROLS      {% endcomment %}
+            {% comment %} ========================== {% endcomment %}
             
-            <!-- Left Sidebar Toggle - Mobile view only. Uses the shared
+            {% comment %} Left Sidebar Toggle - Mobile view only. Uses the shared
                  resolver (navigation/sidebar-config.html) so this gate can
-                 never drift from the default layout's aside. -->
+                 never drift from the default layout's aside. {% endcomment %}
             {% include navigation/sidebar-config.html %}
 
-            {% if sidebar_has_content %}
-              {%- comment -%}
-                When site.navigation.unified_mobile_drawer is true, the sidebar
-                toggle opens the consolidated drawer (Browse tab pre-selected)
-                instead of the legacy #bdSidebar offcanvas.
-              {%- endcomment -%}
+            {%- comment -%}
+              Two conditions, and BOTH are required (issue #373).
+
+              `sidebar_has_content` asks "is there nav content to show". It is
+              not enough on its own: this include is pulled in by
+              _layouts/root.html, so it renders on EVERY layout, while
+              `#bdSidebar` is emitted by _layouts/default.html alone. On a
+              layout that inherits root directly — admin, stats, 404, section,
+              home … — the toggle rendered pointing at an offcanvas that was
+              never in the document: a dead control, and aria-controls
+              dangling into nothing for assistive tech. Measured before the
+              fix: 37 of 415 built pages.
+
+              The unified drawer is exempt because #zer0UnifiedDrawer IS
+              emitted from root.html, so it exists on every layout — that
+              target is always real and the toggle is always live.
+            {%- endcomment -%}
+            {% if sidebar_has_content and site.navigation.unified_mobile_drawer %}
+              {%- assign _sidebar_toggle_ok = true -%}
+            {% elsif sidebar_has_content and sidebar_offcanvas_rendered %}
+              {%- assign _sidebar_toggle_ok = true -%}
+            {% else %}
+              {%- assign _sidebar_toggle_ok = false -%}
+            {% endif %}
+            {% if _sidebar_toggle_ok %}
               {%- if site.navigation.unified_mobile_drawer -%}
                 {%- assign _sidebar_target = "#zer0UnifiedDrawer" -%}
                 {%- assign _sidebar_controls = "zer0UnifiedDrawer" -%}
@@ -98,11 +117,11 @@
             </div>
             {% endif %}
 
-            <!-- ========================== -->
-            <!-- BRAND AND HOME NAVIGATION -->
-            <!-- ========================== -->
+            {% comment %} ========================== {% endcomment %}
+            {% comment %} BRAND AND HOME NAVIGATION {% endcomment %}
+            {% comment %} ========================== {% endcomment %}
             <div class="navbar-brand-group d-inline-flex align-items-center gap-2">
-                <!-- Home Navigation Button (Desktop only) -->
+                {% comment %} Home Navigation Button (Desktop only) {% endcomment %}
                 <div class="navbar-home-links d-none" role="navigation" aria-label="Quick navigation">
                     {%- assign nav_home = site.data.navigation.home -%}
                     {%- if nav_home and nav_home.size > 0 -%}
@@ -118,18 +137,18 @@
                     {%- endif -%}
                 </div>
                 
-                <!-- Brand Logo Link to Root -->
-                <!-- Logo path configured in _config.yml -->
+                {% comment %} Brand Logo Link to Root {% endcomment %}
+                {% comment %} Logo path configured in _config.yml {% endcomment %}
                 {% capture logo_path %}{{ site.logo }}{% endcapture %}
                 <a class="navbar-brand" href="{{ site.baseurl }}/" aria-label="Home - {{ site.title }}" {% if page.url == '/' %}aria-current="page"{% endif %}>
                     <img src="{{ logo_path | relative_url }}" alt="{{ site.title }} logo" width="30" height="30">
                 </a>
             </div>
             
-            <!-- ========================== -->
-            <!-- SITE BRANDING SECTION     -->
-            <!-- ========================== -->
-            <!-- Site title and subtitle display -->
+            {% comment %} ========================== {% endcomment %}
+            {% comment %} SITE BRANDING SECTION     {% endcomment %}
+            {% comment %} ========================== {% endcomment %}
+            {% comment %} Site title and subtitle display {% endcomment %}
             {% include core/branding.html %}
 
             </div>
@@ -141,21 +160,21 @@
             {%- endcomment -%}
             {% include navigation/navbar-mobile-quicklinks.html %}
     
-            <!-- ========================== -->
-            <!-- MAIN NAVIGATION MENU      -->
-            <!-- ========================== -->
-            <!-- Primary navigation items from _data/navigation.yml -->
+            {% comment %} ========================== {% endcomment %}
+            {% comment %} MAIN NAVIGATION MENU      {% endcomment %}
+            {% comment %} ========================== {% endcomment %}
+            {% comment %} Primary navigation items from _data/navigation.yml {% endcomment %}
             {% include navigation/navbar.html %}
 
-            <!-- ========================== -->
-            <!-- UTILITY CONTROLS          -->
-            <!-- ========================== -->
+            {% comment %} ========================== {% endcomment %}
+            {% comment %} UTILITY CONTROLS          {% endcomment %}
+            {% comment %} ========================== {% endcomment %}
             <div class="navbar-utility-controls d-flex align-items-center flex-shrink-0" role="group" aria-label="Utility controls">
-                <!-- Language selection lives in the Settings offcanvas
+                {% comment %} Language selection lives in the Settings offcanvas
                      (components/info-section.html, Appearance tab) so the bar
-                     keeps its width for the main navigation items. -->
+                     keeps its width for the main navigation items. {% endcomment %}
 
-                <!-- Search Modal Toggle -->
+                {% comment %} Search Modal Toggle {% endcomment %}
                 <button
                     class="btn nav-search-button"
                     type="button"
@@ -170,7 +189,7 @@
                     <kbd class="nav-search-kbd d-none d-xl-inline-flex" aria-hidden="true">/</kbd>
                 </button>
 
-                <!-- Settings Offcanvas Toggle -->
+                {% comment %} Settings Offcanvas Toggle {% endcomment %}
                 <button
                     class="btn nav-settings-button d-none d-lg-inline-flex"
                     type="button"
@@ -183,7 +202,7 @@
                     <i class="{{site.default_icon}} bi-gear" aria-hidden="true"></i>
                 </button>
 
-                <!-- Navigation Menu Toggle - Mobile view -->
+                {% comment %} Navigation Menu Toggle - Mobile view {% endcomment %}
                 {%- if site.navigation.unified_mobile_drawer -%}
                   {%- assign _menu_target = "#zer0UnifiedDrawer" -%}
                   {%- assign _menu_controls = "zer0UnifiedDrawer" -%}
@@ -206,12 +225,12 @@
         </nav>
     </div>
 
-    <!-- ========================== -->
-    <!-- PROGRESS BAR MOUNT POINT  -->
-    <!-- ========================== -->
-    <!-- Nanobar mounts here when site.nanobar.position == "navbar" so the bar
+    {% comment %} ========================== {% endcomment %}
+    {% comment %} PROGRESS BAR MOUNT POINT  {% endcomment %}
+    {% comment %} ========================== {% endcomment %}
+    {% comment %} Nanobar mounts here when site.nanobar.position == "navbar" so the bar
          renders as a thin strip directly under the header. For "top" / "bottom"
-         the bar floats fixed to the viewport and no mount is needed. -->
+         the bar floats fixed to the viewport and no mount is needed. {% endcomment %}
     {%- assign _nb_pos = site.nanobar.position | default: "top" -%}
     {%- if site.nanobar.enabled != false and _nb_pos == "navbar" -%}
     <div id="top-progress-target" class="nanobar-mount" aria-hidden="true"></div>