jekyll-theme-zer0 1.28.0 → 1.30.0

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,22 +51,34 @@
 <script defer src="{{ '/assets/js/table-copy.js' | relative_url }}"></script>
 <script defer src="{{ '/assets/js/ui-enhancements.js' | relative_url }}"></script>
 
-<!-- ================================ -->
-<!-- THIRD PARTY INTEGRATIONS        -->
-<!-- ================================ -->
+{% 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. {% endcomment %}
+{% include components/page-views-init.html %}
 
-<!-- Mermaid Diagrams - Conditional loading based on page front matter -->
+{% comment %} ================================ {% endcomment %}
+{% comment %} THIRD PARTY INTEGRATIONS        {% endcomment %}
+{% comment %} ================================ {% endcomment %}
+
+{% 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). {% endcomment %}
+{% if page.layout == "recipe" or page.recipe_tools %}
+<script defer src="{{ '/assets/js/recipe-scaler.js' | relative_url }}"></script>
+{% endif %}
+
+{% 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: {
@@ -79,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 %}
@@ -123,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 -->
-        <!-- ========================== -->
-        <nav class="container-xl order-2 order-lg-1 d-flex align-items-center gap-1 flex-nowrap navbar-main w-100" aria-label="Primary navigation">
+        {% 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,33 +160,36 @@
             {%- 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 Toggle (renders only when translation.languages is set) -->
-                {% include components/language-toggle.html %}
+                {% 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. {% endcomment %}
 
-                <!-- Search Modal Toggle -->
+                {% comment %} Search Modal Toggle {% endcomment %}
                 <button
                     class="btn nav-search-button"
                     type="button"
                     data-search-toggle
                     aria-label="{{ ui.shortcuts_search | default: 'Open search' }}"
                     aria-haspopup="dialog"
-                    title="{{ ui.search_button_label | default: 'Search' }}"
+                    aria-keyshortcuts="/ Meta+K Control+K"
+                    title="{{ ui.search_button_title | default: 'Search — press / or Ctrl+K' }}"
                 >
                     <i class="{{site.default_icon}} bi-search" aria-hidden="true"></i>
                     <span class="nav-link-text d-none d-xl-inline ms-1">{{ ui.search_button_label | default: "Search" }}</span>
+                    <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"
@@ -180,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" -%}
@@ -203,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>

data/_includes/docs/bootstrap-docs.html

@@ -1,6 +1,6 @@
-<!-- Style.html 
+{% comment %} Style.html 
      _includes/style.html 
--->
+{% endcomment %}
 
 <div class="bd-cheatsheet container-fluid">
     <section id="content">
@@ -933,7 +933,7 @@
               <li><a class="dropdown-item" href="#">Another action</a></li>
               <li><a class="dropdown-item" href="#">Something else here</a></li>
             </ul>
-          </div><!-- /btn-group -->
+          </div>{% comment %} /btn-group {% endcomment %}
           <div class="btn-group">
             <button type="button" class="btn btn-secondary">Secondary</button>
             <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
@@ -944,7 +944,7 @@
               <li><a class="dropdown-item" href="#">Another action</a></li>
               <li><a class="dropdown-item" href="#">Something else here</a></li>
             </ul>
-          </div><!-- /btn-group -->
+          </div>{% comment %} /btn-group {% endcomment %}
           <div class="btn-group">
             <button type="button" class="btn btn-success">Success</button>
             <button type="button" class="btn btn-success dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
@@ -955,7 +955,7 @@
               <li><a class="dropdown-item" href="#">Another action</a></li>
               <li><a class="dropdown-item" href="#">Something else here</a></li>
             </ul>
-          </div><!-- /btn-group -->example-divider
+          </div>{% comment %} /btn-group {% endcomment %}example-divider
           <div class="btn-group">
             <button type="button" class="btn btn-info">Info</button>
             <button type="button" class="btn btn-info dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
@@ -966,7 +966,7 @@
               <li><a class="dropdown-item" href="#">Another action</a></li>
               <li><a class="dropdown-item" href="#">Something else here</a></li>
             </ul>
-          </div><!-- /btn-group -->
+          </div>{% comment %} /btn-group {% endcomment %}
           <div class="btn-group">
             <button type="button" class="btn btn-warning">Warning</button>
             <button type="button" class="btn btn-warning dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
@@ -977,7 +977,7 @@
               <li><a class="dropdown-item" href="#">Another action</a></li>
               <li><a class="dropdown-item" href="#">Something else here</a></li>
             </ul>
-          </div><!-- /btn-group -->
+          </div>{% comment %} /btn-group {% endcomment %}
           <div class="btn-group">
             <button type="button" class="btn btn-danger">Danger</button>
             <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
@@ -988,7 +988,7 @@
               <li><a class="dropdown-item" href="#">Another action</a></li>
               <li><a class="dropdown-item" href="#">Something else here</a></li>
             </ul>
-          </div><!-- /btn-group -->
+          </div>{% comment %} /btn-group {% endcomment %}
           </div></div>
           <div class="bd-example-snippet bd-code-snippet"><div class="bd-example">
           <div class="btn-group w-100 align-items-center justify-content-between flex-wrap">

data/_includes/landing/landing-install-cards.html

@@ -1,4 +1,4 @@
-<!-- Installation method cards; uses site.resources.* and environment where helpful -->
+{% comment %} Installation method cards; uses site.resources.* and environment where helpful {% endcomment %}
 <div class="row g-4 justify-content-center">
   <div class="col-12 col-sm-10 col-md-6 col-lg-4">
     <div class="card h-100 border-0 shadow-sm">
@@ -55,7 +55,7 @@ cd &lt;you&gt;.github.io
   </div>
 </div>
 
-<!-- Contributing guide call-to-action placed below all cards -->
+{% comment %} Contributing guide call-to-action placed below all cards {% endcomment %}
 <div class="text-center mt-4">
   <a class="btn btn-outline-secondary" href="{{ site.resources.contributing | default: '' | join: '' | default: '#' }}" target="_blank" rel="noopener">
     <i class="bi bi-journal-text me-2"></i>Read the Contributing Guide

data/_includes/landing/landing-quick-links.html

@@ -1,4 +1,4 @@
-<!-- Quick Links bar for landing page; uses site.resources config -->
+{% comment %} Quick Links bar for landing page; uses site.resources config {% endcomment %}
 <div class="bg-dark text-white py-3">
   <div class="container-xl px-4 px-md-5">
     <div class="row g-3 justify-content-center text-center align-items-center">

data/_includes/navigation/admin-nav.html

@@ -1,5 +1,5 @@
 {% comment %} Feature: ZER0-050 {% endcomment %}
-<!--
+{% comment %}
   ===================================================================
   ADMIN NAV — Data-driven sidebar navigation for admin/settings pages
   ===================================================================
@@ -15,7 +15,7 @@
                 _data/navigation/admin.yml
   Used by: _layouts/admin.html
   ===================================================================
--->
+{% endcomment %}
 
 {% assign current_path = page.url %}
 {% assign admin_items = site.data.navigation.admin %}