jekyll-theme-zer0 1.28.0 → 1.29.0

data/_includes/components/language-toggle.html

@@ -2,24 +2,61 @@
 {%- comment -%}
   Component:   language-toggle
   Path:        _includes/components/language-toggle.html
-  Purpose:     Navbar dropdown that switches between the English original and
-               its machine-generated translations (scripts/translate.rb).
-               Shows the source language plus every configured target
-               language; targets without a generated translation for the
-               current page render as disabled entries.
-  Params:      none — reads page.lang / page.url / page.translation_source_url
-               and the generated _data/i18n/manifest.yml.
+  Purpose:     Switches between the English original and its machine-generated
+               translations (scripts/translate.rb). Shows the source language
+               plus every configured target language. Every entry is a live
+               link: a target without a generated translation for the current
+               page falls back to the source page and is explained by one
+               footnote (it used to render as a disabled entry — see T-038).
+  Params:      variant (string, optional, default "navbar")
+                 - "navbar" — compact dropdown for the header utility cluster
+                 - "panel"  — self-contained "Language" section for the
+                              Settings offcanvas (components/info-section.html),
+                              rendered as an always-visible list of choices
+                              with its own <h6> heading
+  Reads:       page.lang / page.url / page.translation_source_url and the
+               generated _data/i18n/manifest.yml.
   Depends on:  site.translation.* config, site.data.i18n.manifest,
                _data/i18n/languages.yml (display names), core/i18n.html,
-               Bootstrap 5 dropdown, Bootstrap Icons (bi-translate)
+               Bootstrap 5 dropdown (navbar variant only), Bootstrap Icons
+               (bi-translate)
   Notes:       Renders nothing when translation is disabled or no target
                languages are configured. The chosen language is remembered in
                localStorage("zer0-lang") for future UX (no auto-redirect).
                Must NOT be include_cached — the menu is page-dependent.
+               The theme ships the "panel" variant (the navbar is reserved for
+               main navigation); "navbar" stays for consumers that prefer the
+               header dropdown.
+
+               MENU CONTRACT (T-038 / #406) — shared by both variants:
+                 * No DISABLED rows. A target language without a generated
+                   translation is still a link; it goes to the source-language
+                   page and still records the preference in zer0-lang, so the
+                   menu never contains a dead end.
+                 * The current language is marked with a check icon and a
+                   subtle tint — NOT Bootstrap's `.active` primary fill, which
+                   read as a selected nav item rather than "you are here".
+                 * Machine-generated translations carry a small "auto" chip.
+                   The source language never does (a human wrote it), and
+                   neither do untranslated rows (nothing was generated).
+                 * The per-row "(Not yet translated)" text is replaced by ONE
+                   footnote under a divider, referenced from each untranslated
+                   row via aria-describedby. Per-row text was the single
+                   biggest contributor to menu width.
+               Trigger changes (icon-only, no caret) apply to the navbar
+               variant only — the panel has an <h6> heading, not a button.
+
+               New ui keys (lang_machine_translated, lang_machine_translated_title,
+               lang_untranslated_note) live in _data/ui-text.yml `en`. core/i18n.html
+               REPLACES the whole `ui` map on a translated page rather than merging
+               it, so until scripts/translate.rb regenerates _data/i18n/<lang>.yml
+               these keys are absent there — every use below therefore carries a
+               literal `| default:` fallback. Do not remove them.
 {%- endcomment -%}
 {%- assign _lt_langs = site.translation.languages -%}
 {%- if site.translation.enabled and _lt_langs and _lt_langs.size > 0 -%}
 {%- include core/i18n.html -%}
+{%- assign _lt_variant = include.variant | default: 'navbar' -%}
 {%- assign _lt_source = site.translation.source_lang | default: 'en' -%}
 {%- assign _lt_current = page.lang | default: _lt_source -%}
 {%- if _lt_current == _lt_source -%}
@@ -30,25 +67,117 @@
 {%- assign _lt_entry = site.data.i18n.manifest.pages[_lt_src_url] -%}
 {%- assign _lt_names = site.data.i18n.languages -%}
 {%- assign _lt_source_name = _lt_names[_lt_source].native | default: _lt_source -%}
+{%- comment -%}
+  Display name of the language being read, for the trigger's title/aria — the
+  icon-only button has no visible text, so the accessible name has to carry it.
+{%- endcomment -%}
+{%- if _lt_current == _lt_source -%}
+  {%- assign _lt_current_name = _lt_source_name -%}
+{%- else -%}
+  {%- assign _lt_current_name = _lt_names[_lt_current].native | default: _lt_current -%}
+{%- endif -%}
+{%- comment -%}
+  Does ANY target language lack a translation of this page? Drives whether the
+  footnote + divider render at all — an all-translated menu shows neither.
+  A target we are currently reading is by definition translated.
+{%- endcomment -%}
+{%- assign _lt_untranslated = 0 -%}
+{%- for _lt_l in _lt_langs -%}
+  {%- unless _lt_l == _lt_current or _lt_entry[_lt_l] -%}
+    {%- assign _lt_untranslated = _lt_untranslated | plus: 1 -%}
+  {%- endunless -%}
+{%- endfor -%}
+{%- assign _lt_note_id = 'zer0-lang-untranslated-note' -%}
+{%- assign _lt_auto_label = ui.lang_machine_translated | default: 'auto' -%}
+{%- assign _lt_auto_title = ui.lang_machine_translated_title | default: 'Machine-generated translation' -%}
+{%- assign _lt_note_text = ui.lang_untranslated_note | default: 'Marked languages are not yet translated — those links open the original.' -%}
+{%- assign _lt_fallback_url = _lt_src_url | default: '/' | relative_url -%}
+{%- if _lt_variant == 'panel' -%}
+<div class="mb-4 nav-lang-panel" id="zer0-lang-toggle">
+    <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
+        <i class="bi bi-translate me-1" aria-hidden="true"></i>{{ ui.lang_toggle_label | default: "Language" }}
+    </h6>
+    <div class="list-group nav-lang-options" role="group" aria-label="{{ ui.lang_toggle_aria | default: 'Change language' }}">
+        {%- if _lt_current == _lt_source %}
+        <span class="list-group-item nav-lang-item is-current" aria-current="true">
+            <span class="nav-lang-code">{{ _lt_source | slice: 0, 2 | upcase }}</span>
+            <span class="nav-lang-name">{{ _lt_source_name }}</span>
+            <i class="bi bi-check2 nav-lang-check" aria-hidden="true"></i>
+        </span>
+        {%- else %}
+        <a class="list-group-item list-group-item-action nav-lang-item" data-lang="{{ _lt_source }}" hreflang="{{ _lt_source }}" href="{{ _lt_fallback_url }}">
+            <span class="nav-lang-code">{{ _lt_source | slice: 0, 2 | upcase }}</span>
+            <span class="nav-lang-name">{{ _lt_source_name }}</span>
+        </a>
+        {%- endif %}
+        {%- for _lt_lang in _lt_langs -%}
+        {%- assign _lt_name = _lt_names[_lt_lang].native | default: _lt_lang -%}
+        {%- assign _lt_t = _lt_entry[_lt_lang] %}
+        {%- if _lt_current == _lt_lang %}
+        <span class="list-group-item nav-lang-item is-current" aria-current="true">
+            <span class="nav-lang-code">{{ _lt_lang | slice: 0, 2 | upcase }}</span>
+            <span class="nav-lang-name">{{ _lt_name }}</span>
+            <span class="nav-lang-auto" title="{{ _lt_auto_title }}">{{ _lt_auto_label }}</span>
+            <i class="bi bi-check2 nav-lang-check" aria-hidden="true"></i>
+        </span>
+        {%- elsif _lt_t %}
+        <a class="list-group-item list-group-item-action nav-lang-item" data-lang="{{ _lt_lang }}" hreflang="{{ _lt_lang }}" href="{{ _lt_t.url | relative_url }}">
+            <span class="nav-lang-code">{{ _lt_lang | slice: 0, 2 | upcase }}</span>
+            <span class="nav-lang-name">{{ _lt_name }}</span>
+            <span class="nav-lang-auto" title="{{ _lt_auto_title }}">{{ _lt_auto_label }}</span>
+        </a>
+        {%- else %}
+        {%- comment -%}
+          No translation yet — still a LINK, not a disabled row. It goes to the
+          source page and records the preference, so the reader lands on real
+          content instead of a dead entry. hreflang describes the DESTINATION,
+          which is the source language, not the one that was clicked.
+        {%- endcomment -%}
+        <a class="list-group-item list-group-item-action nav-lang-item is-untranslated" data-lang="{{ _lt_lang }}" hreflang="{{ _lt_source }}" href="{{ _lt_fallback_url }}" aria-describedby="{{ _lt_note_id }}-panel">
+            <span class="nav-lang-code">{{ _lt_lang | slice: 0, 2 | upcase }}</span>
+            <span class="nav-lang-name">{{ _lt_name }}</span>
+            <span class="nav-lang-mark" aria-hidden="true">*</span>
+        </a>
+        {%- endif %}
+        {%- endfor %}
+    </div>
+    {%- if _lt_untranslated > 0 %}
+    <hr class="nav-lang-divider">
+    <p class="nav-lang-note" id="{{ _lt_note_id }}-panel">{{ _lt_note_text }}</p>
+    {%- endif %}
+</div>
+{%- else -%}
 <div class="dropdown nav-lang-toggle" id="zer0-lang-toggle">
+    {%- comment -%}
+      Icon-only, square, and caret-free. `dropdown-toggle` is what draws the
+      Bootstrap caret; it is NOT what wires the dropdown — Bootstrap binds on
+      [data-bs-toggle="dropdown"], so dropping the class costs no behaviour.
+      The visible EN/FR label is gone at every width (it was already hidden
+      below xl), so title + aria-label are the only accessible name and both
+      name the language being read.
+    {%- endcomment -%}
     <button
-        class="btn nav-lang-button dropdown-toggle"
+        class="btn nav-lang-button"
         type="button"
         id="langToggleButton"
         data-bs-toggle="dropdown"
         aria-expanded="false"
         aria-label="{{ ui.lang_toggle_aria | default: 'Change language' }}"
-        title="{{ ui.lang_toggle_label | default: 'Language' }}"
+        title="{{ ui.lang_toggle_label | default: 'Language' }}: {{ _lt_current_name }}"
     >
         <i class="{{ site.default_icon }} bi-translate" aria-hidden="true"></i>
-        <span class="nav-link-text d-none d-xl-inline ms-1 text-uppercase">{{ _lt_current | slice: 0, 2 }}</span>
     </button>
-    <ul class="dropdown-menu dropdown-menu-end" aria-labelledby="langToggleButton">
+    <ul class="dropdown-menu dropdown-menu-end nav-lang-menu" aria-labelledby="langToggleButton">
         <li>
             {%- if _lt_current == _lt_source %}
-            <span class="dropdown-item active" aria-current="true">{{ _lt_source_name }}</span>
+            <span class="dropdown-item nav-lang-item is-current" aria-current="true">
+                <span class="nav-lang-name">{{ _lt_source_name }}</span>
+                <i class="bi bi-check2 nav-lang-check" aria-hidden="true"></i>
+            </span>
             {%- else %}
-            <a class="dropdown-item" data-lang="{{ _lt_source }}" hreflang="{{ _lt_source }}" href="{{ _lt_src_url | default: '/' | relative_url }}">{{ _lt_source_name }}</a>
+            <a class="dropdown-item nav-lang-item" data-lang="{{ _lt_source }}" hreflang="{{ _lt_source }}" href="{{ _lt_fallback_url }}">
+                <span class="nav-lang-name">{{ _lt_source_name }}</span>
+            </a>
             {%- endif %}
         </li>
         {%- for _lt_lang in _lt_langs -%}
@@ -56,23 +185,41 @@
         {%- assign _lt_t = _lt_entry[_lt_lang] %}
         <li>
             {%- if _lt_current == _lt_lang %}
-            <span class="dropdown-item active" aria-current="true">{{ _lt_name }}</span>
+            <span class="dropdown-item nav-lang-item is-current" aria-current="true">
+                <span class="nav-lang-name">{{ _lt_name }}</span>
+                <span class="nav-lang-auto" title="{{ _lt_auto_title }}">{{ _lt_auto_label }}</span>
+                <i class="bi bi-check2 nav-lang-check" aria-hidden="true"></i>
+            </span>
             {%- elsif _lt_t %}
-            <a class="dropdown-item" data-lang="{{ _lt_lang }}" hreflang="{{ _lt_lang }}" href="{{ _lt_t.url | relative_url }}">{{ _lt_name }}</a>
+            <a class="dropdown-item nav-lang-item" data-lang="{{ _lt_lang }}" hreflang="{{ _lt_lang }}" href="{{ _lt_t.url | relative_url }}">
+                <span class="nav-lang-name">{{ _lt_name }}</span>
+                <span class="nav-lang-auto" title="{{ _lt_auto_title }}">{{ _lt_auto_label }}</span>
+            </a>
             {%- else %}
-            <span class="dropdown-item disabled" aria-disabled="true" title="{{ ui.lang_not_available | default: 'Not yet translated' }}">{{ _lt_name }} <small class="text-body-secondary">({{ ui.lang_not_available | default: 'Not yet translated' }})</small></span>
+            {%- comment -%} See the panel variant above — link, never a dead row. {%- endcomment -%}
+            <a class="dropdown-item nav-lang-item is-untranslated" data-lang="{{ _lt_lang }}" hreflang="{{ _lt_source }}" href="{{ _lt_fallback_url }}" aria-describedby="{{ _lt_note_id }}">
+                <span class="nav-lang-name">{{ _lt_name }}</span>
+                <span class="nav-lang-mark" aria-hidden="true">*</span>
+            </a>
             {%- endif %}
         </li>
         {%- endfor %}
+        {%- if _lt_untranslated > 0 %}
+        <li><hr class="dropdown-divider"></li>
+        <li><p class="nav-lang-note" id="{{ _lt_note_id }}">{{ _lt_note_text }}</p></li>
+        {%- endif %}
     </ul>
 </div>
+{%- endif -%}
 <script>
   // Remember the visitor's language pick (no auto-redirect — just preference).
+  // Delegated at document level so it covers both variants and stays correct
+  // if a consumer renders the component more than once per page.
   (function () {
-    var toggle = document.getElementById('zer0-lang-toggle');
-    if (!toggle) return;
-    toggle.addEventListener('click', function (event) {
-      var item = event.target.closest('a.dropdown-item[data-lang]');
+    if (window.__zer0LangPrefWired) return;
+    window.__zer0LangPrefWired = true;
+    document.addEventListener('click', function (event) {
+      var item = event.target.closest('#zer0-lang-toggle a[data-lang]');
       if (!item) return;
       try { localStorage.setItem('zer0-lang', item.getAttribute('data-lang')); } catch (e) { /* private mode */ }
     });

data/_includes/components/page-views-init.html

@@ -0,0 +1,55 @@
+{% comment %} Feature: ZER0-083 {% endcomment %}
+{%- comment -%}
+  Component:   page-views-init
+  Path:        _includes/components/page-views-init.html
+  Purpose:     Bootstrap the page-view counter — inject its configuration and
+               load the behaviour. Renders no visible markup; the badge lives
+               in components/page-views.html.
+  Params:      none — configured via site.page_views
+  Depends on:  assets/js/page-views.js
+  Included by: _includes/core/head.html (once per page)
+  Notes:       Split from the badge include on purpose: the badge may appear
+               many times on a page, this must appear exactly once.
+{%- endcomment -%}
+
+{%- unless site.page_views.enabled -%}{%- comment -%} counter disabled {%- endcomment -%}
+{%- else -%}
+{%- comment -%}
+  `respect_dnt` / `respect_gpc` / `require_consent` default to the PostHog
+  privacy block so a site configures its privacy posture once. Liquid's
+  `default` filter treats `false` as "missing", so each flag is resolved with
+  an if-tag instead — otherwise an explicit `false` would silently flip true.
+{%- endcomment -%}
+{%- assign pv_dnt = true -%}
+{%- if site.page_views.respect_dnt == false -%}{%- assign pv_dnt = false -%}{%- endif -%}
+{%- assign pv_gpc = true -%}
+{%- if site.page_views.respect_gpc == false -%}{%- assign pv_gpc = false -%}{%- endif -%}
+{%- assign pv_consent = false -%}
+{%- if site.page_views.require_consent -%}{%- assign pv_consent = true -%}{%- endif -%}
+{%- assign pv_track = true -%}
+{%- if site.page_views.track == false -%}{%- assign pv_track = false -%}{%- endif -%}
+{%- assign pv_fallback = false -%}
+{%- if site.page_views.fallback_local -%}{%- assign pv_fallback = true -%}{%- endif -%}
+
+<!-- Page-view counter configuration consumed by assets/js/page-views.js -->
+<script id="pageViewsConfig" type="application/json">
+{
+  "enabled": true,
+  "provider": {{ site.page_views.provider | default: "local" | jsonify }},
+  "endpoint": {{ site.page_views.endpoint | default: "" | jsonify }},
+  "method": {{ site.page_views.method | default: "POST" | jsonify }},
+  "countKey": {{ site.page_views.count_key | default: "views" | jsonify }},
+  "dedupe": {{ site.page_views.dedupe | default: "session" | jsonify }},
+  "maxEntries": {{ site.page_views.max_entries | default: 500 }},
+  "track": {{ pv_track | jsonify }},
+  "respectDnt": {{ pv_dnt | jsonify }},
+  "respectGpc": {{ pv_gpc | jsonify }},
+  "requireConsent": {{ pv_consent | jsonify }},
+  "fallbackLocal": {{ pv_fallback | jsonify }},
+  "baseurl": {{ site.baseurl | default: "" | jsonify }},
+  "labelOne": {{ site.page_views.label_one | default: "view" | jsonify }},
+  "labelOther": {{ site.page_views.label_other | default: "views" | jsonify }}
+}
+</script>
+<script defer src="{{ '/assets/js/page-views.js' | relative_url }}"></script>
+{%- endunless -%}

data/_includes/components/page-views.html

@@ -0,0 +1,33 @@
+{% comment %} Feature: ZER0-083 {% endcomment %}
+{%- comment -%}
+  Component:   page-views
+  Path:        _includes/components/page-views.html
+  Purpose:     Inline "N views" badge for a page. Ships hidden and is revealed
+               by assets/js/page-views.js once a count is known, so a page
+               with no data never flashes "0 views".
+  Params:      url        (string, optional, default: page.url) — page to show
+               class      (string, optional, default: "")       — extra classes
+               icon       (string, optional, default: "bi-eye")
+               separator  (bool,   optional, default: false)    — render a
+                          leading "•" INSIDE the badge, so the separator hides
+                          with it in a meta row
+  Depends on:  components/page-views-init.html (config + behaviour, loaded once
+               from core/head.html), _sass/components/_page-views.scss
+  Notes:       Safe to include more than once per page — each badge resolves
+               its own `data-page-views` path. Paths are site-relative and
+               baseurl-free (page.url); page-views.js normalizes the runtime
+               location the same way.
+{%- endcomment -%}
+
+{%- unless site.page_views.enabled -%}{%- comment -%} counter disabled {%- endcomment -%}
+{%- else -%}
+{%- assign pv_path = include.url | default: page.url -%}
+{%- assign pv_class = include.class | default: "" -%}
+{%- assign pv_icon = include.icon | default: "bi-eye" -%}
+<span class="page-views{% if pv_class != "" %} {{ pv_class }}{% endif %}" data-page-views="{{ pv_path | escape }}" hidden>
+  {%- if include.separator -%}<span class="page-views__sep mx-2" aria-hidden="true">•</span>{%- endif -%}
+  <i class="bi {{ pv_icon }} me-1" aria-hidden="true"></i>
+  <span class="page-views__count" data-page-views-count>0</span>
+  <span class="page-views__label" data-page-views-label>{{ site.page_views.label_other | default: "views" }}</span>
+</span>
+{%- endunless -%}

data/_includes/components/recipe-card.html

@@ -0,0 +1,67 @@
+{% comment %} Feature: ZER0-084 {% endcomment %}
+{%- comment -%}
+  Component:   recipe-card
+  Path:        _includes/components/recipe-card.html
+  Purpose:     Index card for one recipe — photo, title, one-line description,
+               and the three facts a cook scans for: total time, what it makes,
+               and how hard it is.
+  Params:      recipe (document, required) — a `recipes` collection doc
+               heading_level (number, optional, default: 3) — the title's
+                 heading level, so a card never skips a level under whatever
+                 heading precedes it
+               class (string, optional, default: "")
+  Depends on:  components/preview-image.html, components/recipe-duration.html,
+               _sass/components/_recipe.scss (.recipe-card)
+  Notes:       Total time comes from `times.total` or prep + cook + rest, so
+               the card never disagrees with the recipe page. The whole card is
+               one link for a large tap target; the facts row is plain text so
+               it stays readable when images fail to load.
+{%- endcomment -%}
+{%- if include.recipe == nil -%}
+  {%- comment -%} ERROR: recipe-card requires `recipe` {%- endcomment -%}
+{%- else -%}
+{%- assign _rc_r = include.recipe -%}
+{%- assign _rc_img = _rc_r.image | default: _rc_r.preview | default: site.teaser -%}
+{%- assign _rc_prep = _rc_r.times.prep | default: 0 -%}
+{%- assign _rc_cook = _rc_r.times.cook | default: 0 -%}
+{%- assign _rc_rest = _rc_r.times.rest | default: 0 -%}
+{%- if _rc_r.times.total -%}
+  {%- assign _rc_total = _rc_r.times.total -%}
+{%- else -%}
+  {%- assign _rc_total = _rc_prep | plus: _rc_cook | plus: _rc_rest -%}
+{%- endif -%}
+{%- capture _rc_total_h -%}{%- include components/recipe-duration.html minutes=_rc_total -%}{%- endcapture -%}
+{%- assign _rc_total_h = _rc_total_h | strip -%}
+<article class="recipe-card h-100 {{ include.class | default: '' }}">
+  <a href="{{ _rc_r.url | relative_url }}" class="recipe-card-link d-flex flex-column h-100 text-decoration-none text-body">
+    {%- if _rc_img -%}
+    <div class="recipe-card-media">
+      {%- include components/preview-image.html src=_rc_img alt=_rc_r.title class="" -%}
+    </div>
+    {%- endif -%}
+    <div class="recipe-card-body">
+      {%- assign _rc_hl = include.heading_level | default: 3 -%}
+      <h{{ _rc_hl }} class="h5 recipe-card-title">{{ _rc_r.title }}</h{{ _rc_hl }}>
+      {%- if _rc_r.description -%}
+      <p class="recipe-card-description small text-body-secondary">{{ _rc_r.description | strip_html | truncate: 120 }}</p>
+      {%- endif -%}
+      <p class="recipe-card-facts small text-body-secondary mb-0">
+        {%- assign _rc_sep = false -%}
+        {%- if _rc_total_h != "" -%}
+          <span class="recipe-card-fact"><i class="bi bi-clock-history me-1" aria-hidden="true"></i>{{ _rc_total_h }}</span>
+          {%- assign _rc_sep = true -%}
+        {%- endif -%}
+        {%- if _rc_r.yield.amount -%}
+          {%- if _rc_sep %}<span class="mx-1" aria-hidden="true">•</span>{% endif -%}
+          <span class="recipe-card-fact"><i class="bi bi-pie-chart me-1" aria-hidden="true"></i>{{ _rc_r.yield.amount }} {{ _rc_r.yield.unit | default: "servings" | escape }}</span>
+          {%- assign _rc_sep = true -%}
+        {%- endif -%}
+        {%- if _rc_r.difficulty -%}
+          {%- if _rc_sep %}<span class="mx-1" aria-hidden="true">•</span>{% endif -%}
+          <span class="recipe-difficulty recipe-difficulty--{{ _rc_r.difficulty | downcase | strip }}">{{ _rc_r.difficulty | capitalize }}</span>
+        {%- endif -%}
+      </p>
+    </div>
+  </a>
+</article>
+{%- endif -%}

data/_includes/components/recipe-duration.html

@@ -0,0 +1,50 @@
+{% comment %} Feature: ZER0-084 {% endcomment %}
+{%- comment -%}
+  Component:   recipe-duration (value resolver — emits a bare string)
+  Path:        _includes/components/recipe-duration.html
+  Purpose:     Format a duration given in MINUTES, either for humans
+               ("1 hr 30 min") or as an ISO 8601 duration for schema.org
+               ("PT1H30M").
+  Params:      minutes (number, required)
+               format (string, optional, default: "human") — "human" | "iso"
+  Depends on:  nothing (pure Liquid arithmetic)
+  Notes:       Emits nothing for a missing or zero duration, so callers can
+               test the captured value and skip the whole row. Days are not
+               special-cased — a 3-day cure reads as "72 hr", which is how
+               recipes actually write long ferments.
+
+               Liquid `assign` writes to the GLOBAL scope even inside an
+               include, so a helper called several times from one caller will
+               clobber the caller's variables if the names collide. Every
+               variable here is therefore prefixed `_rd_`, and the other recipe
+               components use their own prefixes. Keep that up when editing.
+
+               Capture it (this comment is brace-free so it cannot self-execute):
+                 capture total -> include components/recipe-duration.html minutes=90
+{%- endcomment -%}
+{%- assign _rd_m = include.minutes -%}
+{%- if _rd_m == nil or _rd_m == "" or _rd_m <= 0 -%}
+  {%- comment -%} recipe-duration: no duration — emitting nothing {%- endcomment -%}
+{%- else -%}
+{%- assign _rd_total = _rd_m | round -%}
+{%- assign _rd_hours = _rd_total | divided_by: 60 -%}
+{%- assign _rd_mins = _rd_total | modulo: 60 -%}
+{%- if include.format == "iso" -%}
+PT{% if _rd_hours > 0 %}{{ _rd_hours }}H{% endif %}{% if _rd_mins > 0 %}{{ _rd_mins }}M{% endif %}
+{%- else -%}
+{%- comment -%}
+  Built by appending rather than by emitting the separator from inside an
+  `if`: Liquid treats a block whose body is only whitespace as blank and
+  drops it, which silently swallowed the space in "12 hr 45 min".
+{%- endcomment -%}
+{%- assign _rd_out = "" -%}
+{%- if _rd_hours > 0 -%}
+  {%- assign _rd_out = _rd_out | append: _rd_hours | append: " hr" -%}
+{%- endif -%}
+{%- if _rd_mins > 0 -%}
+  {%- if _rd_out != "" -%}{%- assign _rd_out = _rd_out | append: " " -%}{%- endif -%}
+  {%- assign _rd_out = _rd_out | append: _rd_mins | append: " min" -%}
+{%- endif -%}
+{{- _rd_out -}}
+{%- endif -%}
+{%- endif -%}

data/_includes/components/recipe-grams.html

@@ -0,0 +1,58 @@
+{% comment %} Feature: ZER0-084 {% endcomment %}
+{%- comment -%}
+  Component:   recipe-grams (value resolver — emits a bare number)
+  Path:        _includes/components/recipe-grams.html
+  Purpose:     Convert one recipe quantity to grams so ratio tables and
+               baker's percentages can be computed at BUILD time (no JS needed).
+  Params:      qty (number, required)            — the amount as authored
+               unit (string, optional)           — g, kg, oz, lb, ml, l, tsp,
+                                                   tbsp, cup, fl oz, pint, …
+               grams_per_cup (number, optional)  — density, required to convert
+                                                   a VOLUME into a weight
+  Depends on:  nothing (pure Liquid arithmetic)
+  Notes:       Outputs a bare number rounded to 1 decimal, or nothing at all
+               when the unit is unknown/countable ("clove", "egg") or a volume
+               with no density. Callers MUST treat empty output as "unknown".
+               Mirrors the unit table in assets/js/recipe-scaler.js — change
+               both together.
+
+               Liquid `assign` writes to the GLOBAL scope even inside an
+               include, so every variable here is prefixed `_rg_` to keep
+               repeated calls from clobbering the caller's own variables.
+
+               Capture it (this comment is brace-free so it cannot self-execute):
+                 capture grams -> include components/recipe-grams.html
+                                    qty=i.qty unit=i.unit grams_per_cup=density
+{%- endcomment -%}
+{%- if include.qty == nil or include.qty == "" -%}
+  {%- comment -%} ERROR: recipe-grams requires `qty` {%- endcomment -%}
+{%- else -%}
+{%- assign _rg_u = include.unit | default: "" | downcase | strip | replace: ".", "" | replace: "-", " " -%}
+{%- assign _rg_mass = 0 -%}
+{%- assign _rg_ml = 0 -%}
+{%- case _rg_u -%}
+  {%- when "g" or "gram" or "grams" or "gr" -%}{%- assign _rg_mass = 1 -%}
+  {%- when "kg" or "kilogram" or "kilograms" -%}{%- assign _rg_mass = 1000 -%}
+  {%- when "mg" or "milligram" or "milligrams" -%}{%- assign _rg_mass = 0.001 -%}
+  {%- when "oz" or "ounce" or "ounces" -%}{%- assign _rg_mass = 28.3495 -%}
+  {%- when "lb" or "lbs" or "pound" or "pounds" -%}{%- assign _rg_mass = 453.592 -%}
+  {%- when "ml" or "milliliter" or "milliliters" or "millilitre" or "millilitres" or "cc" -%}{%- assign _rg_ml = 1 -%}
+  {%- when "l" or "liter" or "liters" or "litre" or "litres" -%}{%- assign _rg_ml = 1000 -%}
+  {%- when "dl" or "deciliter" or "deciliters" -%}{%- assign _rg_ml = 100 -%}
+  {%- when "tsp" or "teaspoon" or "teaspoons" -%}{%- assign _rg_ml = 4.92892 -%}
+  {%- when "tbsp" or "tbs" or "tablespoon" or "tablespoons" -%}{%- assign _rg_ml = 14.7868 -%}
+  {%- when "cup" or "cups" -%}{%- assign _rg_ml = 236.588 -%}
+  {%- when "fl oz" or "floz" or "fluid ounce" or "fluid ounces" -%}{%- assign _rg_ml = 29.5735 -%}
+  {%- when "pint" or "pints" or "pt" -%}{%- assign _rg_ml = 473.176 -%}
+  {%- when "quart" or "quarts" or "qt" -%}{%- assign _rg_ml = 946.353 -%}
+  {%- when "gallon" or "gallons" or "gal" -%}{%- assign _rg_ml = 3785.41 -%}
+{%- endcase -%}
+{%- if _rg_mass > 0 -%}
+  {%- assign _rg_g = include.qty | times: _rg_mass -%}
+{{- _rg_g | round: 1 -}}
+{%- elsif _rg_ml > 0 and include.grams_per_cup -%}
+  {%- assign _rg_vol = include.qty | times: _rg_ml -%}
+  {%- assign _rg_g = _rg_vol | times: include.grams_per_cup | divided_by: 236.588 -%}
+{{- _rg_g | round: 1 -}}
+{%- endif -%}
+{%- endif -%}

data/_includes/components/recipe-index.html

@@ -0,0 +1,96 @@
+{% comment %} Feature: ZER0-084 {% endcomment %}
+{%- comment -%}
+  Component:   recipe-index
+  Path:        _includes/components/recipe-index.html
+  Purpose:     Responsive grid of every recipe, grouped into course sections
+               ("Breads & Doughs", "Desserts") — drop it on a cookbook landing
+               page, a home page, or anywhere else recipes should be browsable.
+  Params:      cookbook (string, optional) — a cookbook slug; only recipes
+                 whose `cookbook:` matches are listed. Omit for every recipe.
+               heading (string, optional) — overall section heading (h2)
+               heading_level (string, optional, default: "h2")
+               grouped (bool, optional, default: true) — false renders one flat
+                 grid with no course headings
+               class (string, optional, default: "")
+  Depends on:  components/recipe-card.html, the `recipes` collection,
+               _data/recipe_courses.yml, _sass/components/_recipe.scss
+  Notes:       Cookbook landing pages (`layout: cookbook`) are excluded — this
+               lists recipes, not covers. Courses render in the order they
+               appear in _data/recipe_courses.yml, then any course a recipe
+               used but the data file never declared. A recipe with no
+               `course:` falls under `uncategorized`. Recipes sort by title
+               within a course.
+{%- endcomment -%}
+{%- assign _rx_all = site.recipes | where_exp: "doc", "doc.layout != 'cookbook'" -%}
+{%- if include.cookbook -%}
+  {%- assign _rx_all = _rx_all | where: "cookbook", include.cookbook -%}
+{%- endif -%}
+{%- if _rx_all == nil or _rx_all.size == 0 -%}
+  {%- comment -%} recipe-index: no recipes found{% if include.cookbook %} for cookbook "{{ include.cookbook }}"{% endif %} — skipping render {%- endcomment -%}
+{%- else -%}
+{%- assign _rx_hl = include.heading_level | default: "h2" -%}
+{%- comment -%}
+  Heading levels must not skip. Course headings sit one level below the
+  section heading when there is one, and AT the section level when there is
+  not — otherwise a cookbook page goes h1 → h3. Card titles always sit one
+  level below whatever the course headings ended up being.
+{%- endcomment -%}
+{%- if include.heading -%}
+  {%- assign _rx_course_level = _rx_hl | remove: "h" | plus: 1 -%}
+{%- else -%}
+  {%- assign _rx_course_level = _rx_hl | remove: "h" | plus: 0 -%}
+{%- endif -%}
+{%- assign _rx_card_level = _rx_course_level | plus: 1 -%}
+<section class="recipe-index {{ include.class | default: '' }}">
+  {%- if include.heading -%}
+  <{{ _rx_hl }} class="mb-4">{{ include.heading }}</{{ _rx_hl }}>
+  {%- endif -%}
+
+  {%- if include.grouped == false -%}
+  <div class="row row-cols-1 row-cols-sm-2 row-cols-lg-3 g-4">
+    {%- assign _rx_sorted = _rx_all | sort: "title" -%}
+    {%- for _rx_r in _rx_sorted -%}
+    <div class="col">{%- include components/recipe-card.html recipe=_rx_r heading_level=_rx_course_level -%}</div>
+    {%- endfor -%}
+  </div>
+  {%- else -%}
+  {%- assign _rx_default_course = "uncategorized" -%}
+  {%- assign _rx_groups = _rx_all | group_by_exp: "doc", "doc.course | default: _rx_default_course" -%}
+
+  {%- comment -%} Shelf order: courses declared in _data/recipe_courses.yml first (file order), then any others. {%- endcomment -%}
+  {%- assign _rx_order = "," -%}
+  {%- for _rx_pair in site.data.recipe_courses -%}
+    {%- assign _rx_needle = _rx_pair[0] | prepend: "," | append: "," -%}
+    {%- unless _rx_order contains _rx_needle -%}
+      {%- for _rx_g in _rx_groups -%}{%- if _rx_g.name == _rx_pair[0] -%}{%- assign _rx_order = _rx_order | append: _rx_pair[0] | append: "," -%}{%- endif -%}{%- endfor -%}
+    {%- endunless -%}
+  {%- endfor -%}
+  {%- for _rx_g in _rx_groups -%}
+    {%- assign _rx_needle = _rx_g.name | prepend: "," | append: "," -%}
+    {%- unless _rx_order contains _rx_needle -%}{%- assign _rx_order = _rx_order | append: _rx_g.name | append: "," -%}{%- endunless -%}
+  {%- endfor -%}
+  {%- assign _rx_order_list = _rx_order | split: "," -%}
+
+  {%- for _rx_name in _rx_order_list -%}
+    {%- if _rx_name == "" -%}{%- continue -%}{%- endif -%}
+    {%- assign _rx_group = _rx_groups | where: "name", _rx_name | first -%}
+    {%- if _rx_group == nil -%}{%- continue -%}{%- endif -%}
+    {%- assign _rx_meta = site.data.recipe_courses[_rx_name] -%}
+    {%- assign _rx_recipes = _rx_group.items | sort: "title" -%}
+  <div class="recipe-course mb-5" id="course-{{ _rx_name }}">
+    <h{{ _rx_course_level }} class="h4 mb-1">
+      <i class="bi {{ _rx_meta.icon | default: 'bi-journal-bookmark' }} me-2" aria-hidden="true"></i>{{ _rx_meta.title | default: _rx_name | escape }}
+    </h{{ _rx_course_level }}>
+    {%- if _rx_meta.tagline -%}
+    <p class="text-body-secondary mb-3">{{ _rx_meta.tagline | escape }}</p>
+    {%- endif -%}
+    <div class="row row-cols-1 row-cols-sm-2 row-cols-lg-3 g-4">
+      {%- for _rx_r in _rx_recipes -%}
+      <div class="col">{%- include components/recipe-card.html recipe=_rx_r heading_level=_rx_card_level -%}</div>
+      {%- endfor -%}
+    </div>
+  </div>
+  {%- endfor -%}
+  {%- endif -%}
+</section>
+{%- endif -%}