jekyll-theme-zer0 1.28.0 → 1.30.0

data/_includes/components/recipe-steps.html

@@ -0,0 +1,86 @@
+{% comment %} Feature: ZER0-084 {% endcomment %}
+{%- comment -%}
+  Component:   recipe-steps
+  Path:        _includes/components/recipe-steps.html
+  Purpose:     The numbered method for one recipe — optionally split into
+               sections ("Day 1", "Assembly"), with per-step timings,
+               convertible temperatures, and step photos.
+  Params:      steps (array, optional, default: page.steps)
+               heading (string, optional, default: "Method")
+               heading_level (string, optional, default: "h2")
+  Depends on:  components/recipe-temp.html, components/recipe-duration.html,
+               _sass/components/_recipe.scss
+  Notes:       A step is either a plain string or a hash of
+               {text, title, time, temp_f, temp_c, image, image_alt, note}.
+               Sections are {section, items} hashes; numbering continues across
+               them via the <ol start> attribute so "step 7" means step 7 no
+               matter which section it lives in. Step text is markdownified, so
+               links and emphasis work. itemprop="recipeInstructions" marks
+               each step for schema.org.
+{%- endcomment -%}
+{%- assign _rs_steps = include.steps | default: page.steps -%}
+{%- if _rs_steps == nil or _rs_steps.size == 0 -%}
+  {%- comment -%} recipe-steps: no `steps` front matter — skipping render {%- endcomment -%}
+{%- else -%}
+{%- assign _rs_hl = include.heading_level | default: "h2" -%}
+{%- assign _rs_sub = _rs_hl | remove: "h" | plus: 1 -%}
+{%- assign _rs_n = 0 -%}
+<section class="recipe-steps">
+  <{{ _rs_hl }} class="recipe-section-heading">
+    <i class="bi bi-list-ol me-2" aria-hidden="true"></i>{{ include.heading | default: "Method" }}
+  </{{ _rs_hl }}>
+
+  {%- for _rs_entry in _rs_steps -%}
+    {%- if _rs_entry.items -%}
+      {%- assign _rs_section = _rs_entry.section | default: _rs_entry.group | default: _rs_entry.title -%}
+      {%- assign _rs_loop_steps = _rs_entry.items -%}
+    {%- else -%}
+      {%- assign _rs_section = nil -%}
+      {%- assign _rs_loop_steps = "" | split: "" | push: _rs_entry -%}
+    {%- endif -%}
+
+    {%- if _rs_section -%}
+  <h{{ _rs_sub }} class="recipe-steps-section-title">{{ _rs_section | escape }}</h{{ _rs_sub }}>
+    {%- endif -%}
+
+  <ol class="recipe-step-list" start="{{ _rs_n | plus: 1 }}">
+    {%- for _rs_s in _rs_loop_steps -%}
+      {%- assign _rs_n = _rs_n | plus: 1 -%}
+      {%- if _rs_s.text or _rs_s.title or _rs_s.image -%}
+        {%- assign _rs_text = _rs_s.text -%}
+      {%- else -%}
+        {%- assign _rs_text = _rs_s -%}
+      {%- endif -%}
+    <li class="recipe-step" itemprop="recipeInstructions">
+      {%- if _rs_s.title -%}
+      <p class="recipe-step-title">{{ _rs_s.title | escape }}</p>
+      {%- endif -%}
+      {%- if _rs_text -%}
+      <div class="recipe-step-text">{{ _rs_text | markdownify }}</div>
+      {%- endif -%}
+      {%- if _rs_s.time or _rs_s.temp_f or _rs_s.temp_c -%}
+      <p class="recipe-step-facts">
+        {%- if _rs_s.time -%}
+          {%- capture _rs_dur -%}{%- include components/recipe-duration.html minutes=_rs_s.time -%}{%- endcapture -%}
+        <span class="recipe-step-fact"><i class="bi bi-stopwatch me-1" aria-hidden="true"></i>{{ _rs_dur | strip }}</span>
+        {%- endif -%}
+        {%- if _rs_s.temp_f or _rs_s.temp_c -%}
+        <span class="recipe-step-fact"><i class="bi bi-thermometer-half me-1" aria-hidden="true"></i>{%- include components/recipe-temp.html f=_rs_s.temp_f c=_rs_s.temp_c -%}</span>
+        {%- endif -%}
+      </p>
+      {%- endif -%}
+      {%- if _rs_s.image -%}
+      <figure class="recipe-step-figure">
+        <img src="{{ _rs_s.image | relative_url }}" alt="{{ _rs_s.image_alt | default: '' | escape }}" loading="lazy" decoding="async" class="img-fluid rounded">
+        {%- if _rs_s.caption -%}<figcaption class="small text-body-secondary mt-1">{{ _rs_s.caption | escape }}</figcaption>{%- endif -%}
+      </figure>
+      {%- endif -%}
+      {%- if _rs_s.note -%}
+      <p class="recipe-step-note small">{{ _rs_s.note | escape }}</p>
+      {%- endif -%}
+    </li>
+    {%- endfor -%}
+  </ol>
+  {%- endfor -%}
+</section>
+{%- endif -%}

data/_includes/components/recipe-temp.html

@@ -0,0 +1,45 @@
+{% comment %} Feature: ZER0-084 {% endcomment %}
+{%- comment -%}
+  Component:   recipe-temp
+  Path:        _includes/components/recipe-temp.html
+  Purpose:     A temperature that follows the reader's unit choice — oven
+               settings, water temperature, doneness targets. Renders BOTH
+               scales by default so the page is complete without JavaScript;
+               the scaler then narrows it to whichever system is selected.
+  Params:      f (number, optional) — degrees Fahrenheit
+               c (number, optional) — degrees Celsius
+                 (give either one; the other is derived)
+               label (string, optional, default: "") — prefix, e.g. "Oven"
+               class (string, optional, default: "")
+  Depends on:  assets/js/recipe-scaler.js, _sass/components/_recipe.scss
+  Notes:       Derived values round to the nearest 5° above 100° — the
+               precision an oven dial actually has — and to the nearest degree
+               below it. Author both `f:` and `c:` to pin exact values.
+               Drop it straight into recipe prose:
+                 include components/recipe-temp.html f=375
+{%- endcomment -%}
+{%- if include.f == nil and include.c == nil -%}
+  {%- comment -%} ERROR: recipe-temp requires `f` or `c` {%- endcomment -%}
+{%- else -%}
+{%- if include.f != nil -%}
+  {%- assign _rt_f = include.f | round -%}
+{%- else -%}
+  {%- assign _rt_fraw = include.c | times: 9.0 | divided_by: 5.0 | plus: 32 -%}
+  {%- if _rt_fraw >= 100 -%}
+    {%- assign _rt_f = _rt_fraw | divided_by: 5.0 | round | times: 5 -%}
+  {%- else -%}
+    {%- assign _rt_f = _rt_fraw | round -%}
+  {%- endif -%}
+{%- endif -%}
+{%- if include.c != nil -%}
+  {%- assign _rt_c = include.c | round -%}
+{%- else -%}
+  {%- assign _rt_craw = include.f | minus: 32 | times: 5.0 | divided_by: 9.0 -%}
+  {%- if _rt_craw >= 100 -%}
+    {%- assign _rt_c = _rt_craw | divided_by: 5.0 | round | times: 5 -%}
+  {%- else -%}
+    {%- assign _rt_c = _rt_craw | round -%}
+  {%- endif -%}
+{%- endif -%}
+<span class="recipe-temp {{ include.class | default: '' }}" data-recipe-temp data-temp-f="{{ _rt_f }}" data-temp-c="{{ _rt_c }}">{% if include.label %}{{ include.label | escape }} {% endif %}{{ _rt_f }} °F ({{ _rt_c }} °C)</span>
+{%- endif -%}

data/_includes/components/search-modal.html

@@ -1,5 +1,5 @@
 {% comment %} Feature: ZER0-032 {% endcomment %}
-<!--
+{% comment %}
   ===================================================================
   SEARCH MODAL - Site-wide Search Popup
   ===================================================================
@@ -16,7 +16,7 @@
     prevents a dead link on remote-theme Pages builds that lack /sitemap/.
   - Keyboard shortcut handled by navigation keyboard module ("/")
   ===================================================================
--->
+{% endcomment %}
 
 {%- include core/i18n.html lang=include.lang -%}
 {%- assign search_placeholder = ui.search_placeholder_text | default: "Enter your search term..." -%}
@@ -45,9 +45,9 @@
     <div class="modal-dialog modal-dialog-centered">
         <div class="modal-content">
             <div class="modal-header">
-                <h5 class="modal-title" id="siteSearchModalLabel">
+                <h2 class="modal-title h5" id="siteSearchModalLabel">
                     <i class="bi bi-search me-2"></i>Search
-                </h5>
+                </h2>
                 <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
             </div>
             <div class="modal-body">
@@ -72,6 +72,31 @@
                         Press <kbd>/</kbd> or <kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>K</kbd> to open search, <kbd>Esc</kbd> to close.
                     </div>
                 </form>
+                {%- comment -%}
+                  Results were never announced (issue #279): search rewrites the
+                  container below without moving focus, so a screen-reader user
+                  got silence — the visible list changed with nothing entering
+                  the accessibility tree's notification queue.
+
+                  The live region is this dedicated, visually-hidden element
+                  rather than the results container itself. Marking the
+                  container live would announce all eight result titles and
+                  their snippets on every keystroke, which is unusable; a
+                  screen-reader user wants "7 results for jekyll", then to
+                  navigate the list on their own terms.
+
+                  polite, not assertive: results land on each keystroke and an
+                  assertive region would interrupt the user mid-word, cutting
+                  off the query they are still typing.
+
+                  aria-atomic so the summary is read as one message even when
+                  only part of the string changes (8 results -> 7 results).
+                {%- endcomment -%}
+                <div class="visually-hidden"
+                     role="status"
+                     aria-live="polite"
+                     aria-atomic="true"
+                     data-search-status></div>
                 <div class="search-results mt-3" data-search-results>
                     <div class="text-muted small" data-search-empty>Start typing to see results.</div>
                 </div>

data/_includes/components/searchbar.html

@@ -1,9 +1,9 @@
 {% comment %} Feature: ZER0-032 {% endcomment %}
 
-<!-- 
+{% comment %} 
   title: Searchbar and hits
   source: Theme component
--->
+{% endcomment %}
 <div class="container order-1">
     <div id="searchbox" class=""   ></div>
     <div id="hits" class="text-start"></div>

data/_includes/components/shortcuts-modal.html

@@ -30,6 +30,9 @@
           <dt class="col-4 col-sm-3 text-end"><kbd>/</kbd></dt>
           <dd class="col-8 col-sm-9 mb-2">{{ ui.shortcuts_search | default: "Open search" }}</dd>
 
+          <dt class="col-4 col-sm-3 text-end"><kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>K</kbd></dt>
+          <dd class="col-8 col-sm-9 mb-2">{{ ui.shortcuts_search | default: "Open search" }}</dd>
+
           <dt class="col-4 col-sm-3 text-end"><kbd>[</kbd></dt>
           <dd class="col-8 col-sm-9 mb-2">{{ ui.shortcuts_prev_section | default: "Previous section" }}</dd>
 

data/_includes/components/svg-background.html

@@ -1,4 +1,4 @@
-<!--
+{% comment %}
   ===================================================================
   SVG-BACKGROUND — Apply fffuel-style SVG background to a zone
   ===================================================================
@@ -20,7 +20,7 @@
     - _data/theme_backgrounds.yml    (asset paths)
     - _config.yml theme_background   (opacity / blend settings)
   ===================================================================
--->
+{% endcomment %}
 
 {% assign zone = include.zone | default: "body" %}
 {% assign skin = site.theme_skin | default: "dark" %}

data/_includes/components/theme-customizer.html

@@ -1,4 +1,4 @@
-<!--
+{% comment %}
   ===================================================================
   THEME CUSTOMIZER — Skin preview grid with live class swapping
   ===================================================================
@@ -12,7 +12,7 @@
   Dependencies: Bootstrap 5 grid/card, Bootstrap Icons
   Used by: pages/_about/settings/theme.md (Skin Preview tab)
   ===================================================================
--->
+{% endcomment %}
 
 {%- comment -%}
   _data/theme_skins.yml is optional for consumers (remote_theme cannot ship

data/_includes/components/theme-info.html

@@ -1,5 +1,5 @@
 {% comment %} Feature: ZER0-021 {% endcomment %}
-<!--
+{% comment %}
   ===================================================================
   THEME INFO - Compact Theme and Build Information
   ===================================================================
@@ -15,12 +15,12 @@
   Note: environment (Prod/Dev) is shown by env-switcher.html in the
   same Site tab — not duplicated here.
   ===================================================================
--->
+{% endcomment %}
 
 <div class="theme-info-compact">
   <div class="row g-2">
 
-    <!-- Theme -->
+    {% comment %} Theme {% endcomment %}
     <div class="col-12">
       <div class="d-flex align-items-center justify-content-between p-2 bg-body-tertiary rounded">
         <div class="d-flex align-items-center">
@@ -44,7 +44,7 @@
       </div>
     </div>
 
-    <!-- Jekyll & Last Build -->
+    {% comment %} Jekyll & Last Build {% endcomment %}
     <div class="col-6">
       <div class="p-2 bg-body-tertiary rounded text-center">
         <small class="text-body-secondary d-block">Jekyll</small>
@@ -54,12 +54,19 @@
     <div class="col-6">
       <div class="p-2 bg-body-tertiary rounded text-center">
         <small class="text-body-secondary d-block">Last Build</small>
-        <code class="small">{{ site.time | date: "%b %d, %H:%M" }}</code>
+        {%- comment -%}
+          data-testid is the stable hook the pixel-snapshot tier masks on
+          (test/visual/features/appearance-snapshot.spec.js). This stamp has
+          minute resolution, so it becomes an unconditional snapshot flake the
+          moment this panel is shown by default rather than inside a collapsed
+          offcanvas. Don't remove the attribute without updating that mask.
+        {%- endcomment -%}
+        <code class="small" data-testid="theme-build-stamp">{{ site.time | date: "%b %d, %H:%M" }}</code>
       </div>
     </div>
 
     {% if site.repository %}
-    <!-- Repository -->
+    {% comment %} Repository {% endcomment %}
     <div class="col-12">
       <div class="d-flex align-items-center justify-content-between p-2 bg-body-tertiary rounded">
         <div class="d-flex align-items-center">
@@ -74,7 +81,7 @@
     </div>
     {% endif %}
 
-    <!-- Quick Links -->
+    {% comment %} Quick Links {% endcomment %}
     <div class="col-12 mt-2">
       <div class="d-flex flex-wrap gap-2 justify-content-center">
         {% if site.remote_theme %}

data/_includes/components/theme-preview-gallery.html

@@ -1,8 +1,8 @@
 {% comment %} Feature: ZER0-065 {% endcomment %}
-<!--
+{% comment %}
   Theme Preview — component gallery for live skin / mode testing.
   Pair with theme-controls-bar.html and theme-customizer.js.
--->
+{% endcomment %}
 <div class="theme-preview-gallery" id="theme-preview-gallery">
 
   <p class="text-body-secondary">
@@ -11,7 +11,7 @@
     <code>theme_color</code> may take precedence over skin tokens for <code>--zer0-color-*</code> variables.
   </p>
 
-  <!-- Typography -->
+  {% comment %} Typography {% endcomment %}
   <section class="theme-preview-section" id="preview-typography" aria-labelledby="preview-typography-heading">
     <h2 class="h4 theme-preview-heading" id="preview-typography-heading">
       <i class="bi bi-fonts me-2" aria-hidden="true"></i>Typography
@@ -33,7 +33,7 @@
     </div>
   </section>
 
-  <!-- Buttons -->
+  {% comment %} Buttons {% endcomment %}
   <section class="theme-preview-section" id="preview-buttons" aria-labelledby="preview-buttons-heading">
     <h2 class="h4 theme-preview-heading" id="preview-buttons-heading">
       <i class="bi bi-hand-index-thumb me-2" aria-hidden="true"></i>Buttons
@@ -59,7 +59,7 @@
     </div>
   </section>
 
-  <!-- Alerts -->
+  {% comment %} Alerts {% endcomment %}
   <section class="theme-preview-section" id="preview-alerts" aria-labelledby="preview-alerts-heading">
     <h2 class="h4 theme-preview-heading" id="preview-alerts-heading">
       <i class="bi bi-exclamation-triangle me-2" aria-hidden="true"></i>Alerts
@@ -72,7 +72,7 @@
     <div class="alert alert-info" role="alert">Info alert</div>
   </section>
 
-  <!-- Cards -->
+  {% comment %} Cards {% endcomment %}
   <section class="theme-preview-section" id="preview-cards" aria-labelledby="preview-cards-heading">
     <h2 class="h4 theme-preview-heading" id="preview-cards-heading">
       <i class="bi bi-card-heading me-2" aria-hidden="true"></i>Cards
@@ -100,7 +100,7 @@
     </div>
   </section>
 
-  <!-- Forms -->
+  {% comment %} Forms {% endcomment %}
   <section class="theme-preview-section" id="preview-forms" aria-labelledby="preview-forms-heading">
     <h2 class="h4 theme-preview-heading" id="preview-forms-heading">
       <i class="bi bi-input-cursor-text me-2" aria-hidden="true"></i>Forms
@@ -134,7 +134,7 @@
     </div>
   </section>
 
-  <!-- Nav tabs -->
+  {% comment %} Nav tabs {% endcomment %}
   <section class="theme-preview-section" id="preview-tabs" aria-labelledby="preview-tabs-heading">
     <h2 class="h4 theme-preview-heading" id="preview-tabs-heading">
       <i class="bi bi-layout-text-window-reverse me-2" aria-hidden="true"></i>Nav tabs
@@ -152,7 +152,7 @@
     </ul>
   </section>
 
-  <!-- Badges -->
+  {% comment %} Badges {% endcomment %}
   <section class="theme-preview-section" id="preview-badges" aria-labelledby="preview-badges-heading">
     <h2 class="h4 theme-preview-heading" id="preview-badges-heading">
       <i class="bi bi-award me-2" aria-hidden="true"></i>Badges
@@ -168,7 +168,7 @@
     </p>
   </section>
 
-  <!-- Code blocks -->
+  {% comment %} Code blocks {% endcomment %}
   <section class="theme-preview-section" id="preview-code" aria-labelledby="preview-code-heading">
     <h2 class="h4 theme-preview-heading" id="preview-code-heading">
       <i class="bi bi-code-slash me-2" aria-hidden="true"></i>Code blocks
@@ -214,7 +214,7 @@ docker-compose up
 {% endhighlight %}
   </section>
 
-  <!-- Links -->
+  {% comment %} Links {% endcomment %}
   <section class="theme-preview-section" id="preview-links" aria-labelledby="preview-links-heading">
     <h2 class="h4 theme-preview-heading" id="preview-links-heading">
       <i class="bi bi-link-45deg me-2" aria-hidden="true"></i>Links
@@ -226,7 +226,7 @@ docker-compose up
     </p>
   </section>
 
-  <!-- Navbar snippet -->
+  {% comment %} Navbar snippet {% endcomment %}
   <section class="theme-preview-section" id="preview-navbar" aria-labelledby="preview-navbar-heading">
     <h2 class="h4 theme-preview-heading" id="preview-navbar-heading">
       <i class="bi bi-layout-navbar me-2" aria-hidden="true"></i>Navbar snippet
@@ -244,7 +244,7 @@ docker-compose up
     </nav>
   </section>
 
-  <!-- Footer snippet -->
+  {% comment %} Footer snippet {% endcomment %}
   <section class="theme-preview-section" id="preview-footer" aria-labelledby="preview-footer-heading">
     <h2 class="h4 theme-preview-heading" id="preview-footer-heading">
       <i class="bi bi-layout-text-sidebar-reverse me-2" aria-hidden="true"></i>Footer snippet
@@ -269,7 +269,7 @@ docker-compose up
     </footer>
   </section>
 
-  <!-- Table -->
+  {% comment %} Table {% endcomment %}
   <section class="theme-preview-section" id="preview-table" aria-labelledby="preview-table-heading">
     <h2 class="h4 theme-preview-heading" id="preview-table-heading">
       <i class="bi bi-table me-2" aria-hidden="true"></i>Table
@@ -288,7 +288,7 @@ docker-compose up
     </div>
   </section>
 
-  <!-- List group -->
+  {% comment %} List group {% endcomment %}
   <section class="theme-preview-section" id="preview-list-group" aria-labelledby="preview-list-group-heading">
     <h2 class="h4 theme-preview-heading" id="preview-list-group-heading">
       <i class="bi bi-list-ul me-2" aria-hidden="true"></i>List group
@@ -300,7 +300,7 @@ docker-compose up
     </ul>
   </section>
 
-  <!-- Backgrounds -->
+  {% comment %} Backgrounds {% endcomment %}
   <section class="theme-preview-section" id="preview-backgrounds" aria-labelledby="preview-backgrounds-heading">
     <h2 class="h4 theme-preview-heading" id="preview-backgrounds-heading">
       <i class="bi bi-image me-2" aria-hidden="true"></i>Background layers
@@ -324,7 +324,7 @@ docker-compose up
     </div>
   </section>
 
-  <!-- Callouts -->
+  {% comment %} Callouts {% endcomment %}
   <section class="theme-preview-section" id="preview-callouts" aria-labelledby="preview-callouts-heading">
     <h2 class="h4 theme-preview-heading" id="preview-callouts-heading">
       <i class="bi bi-chat-square-text me-2" aria-hidden="true"></i>Callouts
@@ -341,7 +341,7 @@ docker-compose up
     {% include components/callout.html type="danger"  title="Danger"  content=_danger_body %}
   </section>
 
-  <!-- Accordion -->
+  {% comment %} Accordion {% endcomment %}
   <section class="theme-preview-section" id="preview-accordion" aria-labelledby="preview-accordion-heading">
     <h2 class="h4 theme-preview-heading" id="preview-accordion-heading">
       <i class="bi bi-chevron-bar-expand me-2" aria-hidden="true"></i>Accordion
@@ -382,7 +382,7 @@ docker-compose up
     </div>
   </section>
 
-  <!-- Progress & Spinners -->
+  {% comment %} Progress & Spinners {% endcomment %}
   <section class="theme-preview-section" id="preview-progress" aria-labelledby="preview-progress-heading">
     <h2 class="h4 theme-preview-heading" id="preview-progress-heading">
       <i class="bi bi-hourglass-split me-2" aria-hidden="true"></i>Progress &amp; Spinners
@@ -434,7 +434,7 @@ docker-compose up
     </div>
   </section>
 
-  <!-- Breadcrumb & Pagination -->
+  {% comment %} Breadcrumb & Pagination {% endcomment %}
   <section class="theme-preview-section" id="preview-breadcrumb" aria-labelledby="preview-breadcrumb-heading">
     <h2 class="h4 theme-preview-heading" id="preview-breadcrumb-heading">
       <i class="bi bi-signpost-split me-2" aria-hidden="true"></i>Breadcrumb &amp; Pagination
@@ -479,7 +479,7 @@ docker-compose up
     </div>
   </section>
 
-  <!-- Tooltips & Popovers -->
+  {% comment %} Tooltips & Popovers {% endcomment %}
   <section class="theme-preview-section" id="preview-tooltips" aria-labelledby="preview-tooltips-heading">
     <h2 class="h4 theme-preview-heading" id="preview-tooltips-heading">
       <i class="bi bi-chat-dots me-2" aria-hidden="true"></i>Tooltips &amp; Popovers
@@ -503,7 +503,7 @@ docker-compose up
     </div>
   </section>
 
-  <!-- Icons showcase -->
+  {% comment %} Icons showcase {% endcomment %}
   <section class="theme-preview-section" id="preview-icons" aria-labelledby="preview-icons-heading">
     <h2 class="h4 theme-preview-heading" id="preview-icons-heading">
       <i class="bi bi-grid me-2" aria-hidden="true"></i>Bootstrap Icons

data/_includes/content/giscus.html

@@ -1,5 +1,5 @@
 {% comment %} Feature: ZER0-035 {% endcomment %}
-<!--
+{% comment %}
   giscus.html — GitHub Discussions comment system
   ===============================================
 
@@ -30,7 +30,7 @@
   NOTE: do not write a bare `include giscus.html` example with live Liquid
   braces inside this file — Liquid evaluates tags even inside HTML comments,
   which would recursively (and wrongly) try to include "giscus.html".
--->
+{% endcomment %}
 
 <script src="https://giscus.app/client.js"
         data-repo="{{ site.repository }}"

data/_includes/content/intro.html

@@ -1,4 +1,4 @@
-<!--
+{% comment %}
   file: _includes/content/intro.html
   description: Enhanced intro section with share, edit, and improve/report buttons
   path: _includes/content/intro.html
@@ -12,14 +12,14 @@
     - Responsive flex layout: full-width content block, frosted metadata footer with reading time and action buttons
     - Balanced padding and typography hierarchy via bd-intro-* classes
     - Metadata row: author, dates, category, difficulty, tags, view source
--->
+{% endcomment %}
 {%- include core/i18n.html -%}
 {% if page.collection %}
   {% capture page_dir %}{{ site.collections_dir }}{% endcapture %}
   {% assign testvar = "collection exists" %}
 {% endif %}
 
-<!-- Intro Section -->
+{% comment %} Intro Section {% endcomment %}
 
 {% comment %}
   Determine the preview image path. Preview paths can omit the /assets/ prefix.
@@ -228,9 +228,9 @@
           {% endif %}
         </p>
 
-        <!-- Action Buttons Group -->
+        {% comment %} Action Buttons Group {% endcomment %}
         <div class="bd-intro-actions">
-    <!-- Share Button -->
+    {% comment %} Share Button {% endcomment %}
     <div class="dropdown">
       <button class="btn btn-sm btn-info dropdown-toggle" type="button" id="shareDropdownBottom" data-bs-toggle="dropdown" aria-expanded="false">
         <i class="bi bi-share" aria-hidden="true"></i>
@@ -273,10 +273,10 @@
       </ul>
     </div>
 
-    <!-- Improve / Report — opens the page-feedback widget (assets/js/page-feedback.js).
+    {% comment %} Improve / Report — opens the page-feedback widget (assets/js/page-feedback.js).
          Progressive enhancement: this is a real link to the issue form, so it
          works without JavaScript; page-feedback.js intercepts [data-pf-open]
-         clicks and opens the richer capture modal (context + logs + AI) instead. -->
+         clicks and opens the richer capture modal (context + logs + AI) instead. {% endcomment %}
     {% if site.page_feedback.enabled %}
     <a class="btn btn-sm btn-success bd-intro-action-link"
        href="https://github.com/{{ site.repository }}/issues/new?template=page_improvement.yml&labels=page-feedback"
@@ -289,7 +289,7 @@
     </a>
     {% endif %}
 
-    <!-- Edit on GitHub Button -->
+    {% comment %} Edit on GitHub Button {% endcomment %}
     <a href="https://github.com/{{ site.repository }}/blob/{{ repo_branch }}/{{ file_path }}"
        class="btn btn-sm btn-dark bd-intro-action-link"
        target="_blank"

data/_includes/content/jsonld-faq.html

@@ -1,5 +1,5 @@
 {% comment %} Feature: ZER0-054 {% endcomment %}
-<!--
+{% comment %}
   ===================================================================
   JSON-LD FAQ SCHEMA - FAQPage Structured Data
   ===================================================================
@@ -24,7 +24,7 @@
   Dependencies:
   - Page front matter with faq_items array
   ===================================================================
--->
+{% endcomment %}
 
 {% if page.faq_items and page.faq_items.size > 0 %}
 <script type="application/ld+json">

data/_includes/content/jsonld-software.html

@@ -1,4 +1,4 @@
-<!--
+{% comment %}
   ===================================================================
   JSON-LD STRUCTURED DATA - SoftwareApplication + WebPage Schema
   ===================================================================
@@ -9,22 +9,41 @@
            engines to accurately cite and describe the zer0-mistakes
            Jekyll theme as a SoftwareApplication entity.
 
+  OPT-IN ONLY — this describes THE THEME, not the site rendering it.
+  The payload below is hardcoded to zer0-mistakes: its RubyGems download
+  URL, its GitHub repository, its MIT licence, its feature list, its
+  mascot screenshot, and a Person node naming the theme's author. Emitted
+  from a consumer's homepage it asserts, in machine-readable form, that
+  THAT site is a free open-source Ruby gem authored by someone else — e.g.
+  a consulting practice's homepage claiming to be a developer tool.
+
+  It therefore renders only when a site explicitly opts in with
+  `jsonld_software_application: true` in _config.yml, which the theme's own
+  site does. Consumers get no software schema (their standard SEO metadata
+  is unaffected) unless they deliberately turn this on.
+
   Template Logic:
+  - Requires site.jsonld_software_application == true
   - Renders SoftwareApplication schema on the homepage only
   - Links to a WebPage wrapper via @id references
   - Pulls version, author, and description from site config
 
   Dependencies:
-  - _config.yml: site.url, site.title, site.description, site.author
+  - _config.yml: jsonld_software_application, site.url, site.title,
+    site.description, site.author
   - lib/jekyll-theme-zer0/version.rb (version referenced in config)
 
   Usage:
   - Included automatically in _includes/core/head.html
-  - Conditional: only renders when page.permalink == "/"
+  - Conditional: opted in AND page.permalink == "/"
   ===================================================================
--->
+{% endcomment %}
 
-{% if page.permalink == "/" or page.url == "/" %}
+{%- assign _is_homepage = false -%}
+{%- if page.permalink == "/" or page.url == "/" -%}
+  {%- assign _is_homepage = true -%}
+{%- endif -%}
+{% if site.jsonld_software_application and _is_homepage %}
 <script type="application/ld+json">
 {
   "@context": "https://schema.org",