jekyll-theme-zer0 1.29.0 → 1.31.0

data/_sass/components/_ui-enhancements.scss

@@ -53,6 +53,17 @@ img {
   }
 }
 
+// Article hero (_layouts/article.html, figure.featured-hero) — the LCP image.
+// Reserve its box before it loads so the text below never shifts (issue #485).
+// A fixed ratio in CSS rather than width/height attributes: preview assets are
+// 3:2 (1024x683) generated, but some are portrait or external, and a declared
+// intrinsic size that disagrees with the file would itself cause the shift.
+// object-fit: cover (inline on the <img>) crops, never distorts; the inline
+// max-height: 500px still caps the box on wide viewports.
+.featured-hero img {
+  aspect-ratio: 3 / 2;
+}
+
 // Hero content animations
 .bg-primary .container-xl {
   animation: fadeInUp 0.8s ease-out;

data/_sass/core/_navbar.scss

@@ -6,10 +6,12 @@
 // Breakpoints:
 //   - Desktop >= 992px (inline nav; label density via @container bd-nav)
 //   - Mobile < 992px (offcanvas)
-// Nav label tiers (center track / bd-nav container width):
+// Nav label tiers (center track / bd-nav container width) — TWO, never truncating:
 //   - >= 51rem (~816px): icon + full label
-//   - 41-50.99rem: label only (icons dropped so the labels still fit)
-//   - < 41rem (~656px): icon-only (tooltips on lg–xl viewports)
+//   - < 51rem: icon-only (tooltips on lg–xl viewports)
+// Icons are present in BOTH tiers. The old bare-label middle tier and the
+// `text-overflow: ellipsis` safety net were removed in #405 — a truncated
+// label ("Quicksta…") is worse than an icon with a tooltip.
 // ==============================================================================
 
 // -----------------------------------------------------------------------------
@@ -92,6 +94,20 @@
   }
 }
 
+// The below-lg menu toggle carries a visible "Menu" label beside its glyph, so
+// it cannot be confused with the sidebar hamburger sitting next to it (#405).
+.navbar-toggler.navbar-toggler-labeled {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  width: auto;
+
+  .navbar-toggler-text {
+    font-size: 0.9375rem;
+    line-height: 1;
+  }
+}
+
 // Shared icon-only nav styling (applied via @container bd-nav below)
 @mixin navbar-nav-icon-only {
   #bdNavbar .nav-link .nav-link-text {
@@ -137,21 +153,16 @@
     overflow: visible;
   }
 
+  // No transform on :hover. A translate moves the element out from under a
+  // pointer parked on the edge it vacates, hover exits, the element returns —
+  // an infinite flicker. Nav items are thin enough for a 1px lift to do it.
   #bdNavbar .nav-link:hover {
     background-color: var(--bs-tertiary-bg);
-    transform: translateY(-1px);
   }
 
   .nav-hover-dropdown .dropdown-toggle-split {
     padding: var(--zer0-space-1) var(--zer0-space-2);
 
-    &::after {
-      transition: transform 0.2s ease-in-out;
-    }
-
-    &:hover::after {
-      transform: translateY(2px);
-    }
   }
 }
 
@@ -181,12 +192,18 @@
     &:hover {
       color: var(--bs-primary);
       background-color: var(--bs-tertiary-bg);
-      transform: translateY(-1px);
       box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+      // These are `.btn`s, and _ui-enhancements.scss lifts every button by 2px
+      // on hover. Dropping the navbar's own translateY(-1px) is not enough —
+      // the inherited lift flickers the same way. `transform: none` is the
+      // repo's existing corrective pattern (see _post-navigation.scss).
+      transform: none;
     }
     
+    // A pressed cue is safe: :active only holds while the button is held down,
+    // so the pointer cannot leave and re-enter in a loop.
     &:active {
-      transform: translateY(0);
+      transform: translateY(1px);
       box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
     }
     
@@ -197,11 +214,6 @@
     
     i {
       font-size: 1.15rem;
-      transition: transform 0.15s ease-in-out;
-    }
-    
-    &:hover i {
-      transform: scale(1.1);
     }
   }
 }
@@ -400,16 +412,29 @@
     transform: rotate(180deg);
   }
 
-  // Label density degrades in three tiers, measured on the center track
-  // (the `bd-nav` container), so items fit instead of ellipsizing:
+  // Label density has TWO tiers, measured on the center track (the `bd-nav`
+  // container), so items either fit whole or drop to icons — never truncate:
   //   >= 51rem (816px)   icon + label      — the roomy default
-  //   41-50.99rem        label only        — icons dropped to buy ~20px/item
-  //   < 41rem (656px)    icon only         — labels no longer fit at all
-  // Each boundary is the MEASURED width the tier below it needs for the
-  // theme's seven demo items (815px with icons, 647px without), so a tier only
-  // engages once its own content fits. Items keep min-width:0 + ellipsis as the
-  // last-resort safety net for consumers with more or longer entries.
-  @container bd-nav (min-width: 41rem) {
+  //   < 51rem            icon only         — icon + label no longer fits
+  // 51rem is the MEASURED width the icon+label row needs for the theme's seven
+  // demo items (815px), so the upper tier engages exactly when its own content
+  // fits and the lower one takes over otherwise.
+  //
+  // There used to be a middle 41-50.99rem tier that dropped the ICONS to buy
+  // ~20px per item, plus `text-overflow: ellipsis` as a last-resort safety net.
+  // Both are gone (#405): the ellipsis produced "Quicksta…", and a clipped
+  // label is worse than an icon with a tooltip — the icon is at least honest
+  // about being an abbreviation. Icons now survive at every tier, and the
+  // icon-only cutoff moved 41rem -> 51rem to take over the band the middle
+  // tier used to hold. That is a deliberate behaviour change at 656-816px of
+  // center track: those widths used to show bare labels and now show icons,
+  // with `.nav-tooltip` (992-1199px) carrying the name on hover.
+  //
+  // Consumers with materially more (or longer) items than the theme's seven
+  // demo entries can exceed 51rem of content; with shrink and ellipsis both
+  // removed, the row overflows rather than truncates. A container query
+  // cannot measure content, so raise the boundary below if that happens.
+  @container bd-nav (min-width: 51rem) {
     #bdNavbar .navbar-nav {
       gap: 0.125rem;
     }
@@ -418,87 +443,105 @@
       padding: 0.375rem;
     }
 
+    // No `overflow: hidden` / `text-overflow: ellipsis` here: this tier only
+    // engages once the whole icon+label row fits, so a clipped label would be
+    // a bug rather than a fallback. Labels stay whole or the row goes
+    // icon-only (#405).
     #bdNavbar .nav-link .nav-link-text {
       display: inline !important;
       margin-left: 0;
       min-width: 0;
-      overflow: hidden;
-      text-overflow: ellipsis;
       white-space: nowrap;
       transition: opacity 0.15s ease-in-out;
     }
 
+    // Items do NOT shrink in this tier. Shrinking is what produced the
+    // clipped label this tier removes: the tier only engages once the full
+    // icon+label row fits, so an item that shrinks here is being cut for no
+    // reason.
     #bdNavbar .nav-item,
     #bdNavbar .nav-hover-dropdown {
-      flex: 0 1 auto;
+      flex: 0 0 auto;
       min-width: 0;
     }
 
     #bdNavbar .nav-item > .nav-link:not(.dropdown-toggle-split),
     #bdNavbar .nav-hover-dropdown > .nav-link:first-child {
-      flex: 1 1 auto;
+      flex: 0 0 auto;
       min-width: 0;
       max-width: 100%;
-      overflow: hidden;
+      overflow: visible;
       gap: 0.25rem;
     }
 
     #bdNavbar .nav-link i {
       margin-right: 0;
       font-size: 1rem;
-      transition: transform 0.15s ease-in-out;
     }
 
-    #bdNavbar .nav-link:hover {
+    // Hover lives on the ROW, not on each control. With the chevron overlaying
+    // the link's padding box (below), a per-control background would light
+    // only half the row as the pointer crossed it.
+    #bdNavbar .nav-item:not(.nav-hover-dropdown) > .nav-link:hover,
+    #bdNavbar .nav-hover-dropdown:hover > .nav-link:first-child {
       background-color: var(--bs-tertiary-bg);
       border-radius: 0.375rem;
+    }
 
-      i {
-        transform: scale(1.1);
-      }
+    // Chevron merged into the parent link's box (#405). It stays a real
+    // <button> — keyboard reachable, `aria-expanded`/`aria-haspopup` intact —
+    // and is only repositioned: absolutely placed over the right end of the
+    // link's padding, which the link reserves with extra padding-right. There
+    // is no longer a gap between the two, so the dead zone between label and
+    // chevron is gone and the whole row is one hover target.
+    // Every rule below is scoped with #bdNavbar deliberately: the tier's own
+    // `#bdNavbar .nav-link { padding: 0.375rem }` above carries an id, so a
+    // class-only `padding-right` here would lose to it and the chevron would
+    // have no reserved space to sit in.
+    #bdNavbar .nav-hover-dropdown {
+      position: relative;
     }
 
-    .nav-hover-dropdown > .nav-link {
-      border-top-right-radius: 0;
-      border-bottom-right-radius: 0;
+    #bdNavbar .nav-hover-dropdown > .nav-link:first-child {
+      border-radius: 0.375rem;
+      padding-right: 1.25rem;
     }
 
-    .nav-hover-dropdown > .dropdown-toggle-split {
-      border-top-left-radius: 0;
-      border-bottom-left-radius: 0;
+    #bdNavbar .nav-hover-dropdown > .dropdown-toggle-split {
+      position: absolute;
+      top: 0;
+      right: 0;
+      bottom: 0;
+      z-index: 1;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: 1.25rem;
       min-width: 1.25rem;
       min-height: 0;
-      width: 1.25rem;
-      padding-left: 0;
-      padding-right: 0;
-      margin-left: 0 !important;
-    }
-  }
-
-  // Middle tier — the labels fit but the icons no longer do. Dropping the
-  // decorative icon (the label is the accessible name) and tightening the
-  // chevron buys back roughly 20px per item, which is the difference between
-  // "Notebooks" and "N…" at 992-1200px viewports.
-  @container bd-nav (min-width: 41rem) and (max-width: 50.99rem) {
-    #bdNavbar .nav-link i {
-      display: none;
-    }
-
-    #bdNavbar .nav-item > .nav-link:not(.dropdown-toggle-split),
-    #bdNavbar .nav-hover-dropdown > .nav-link:first-child {
-      gap: 0;
+      margin: 0 !important;
+      padding: 0;
+      background-color: transparent;
+      border: 0;
+      border-radius: 0 0.375rem 0.375rem 0;
     }
 
-    // Scoped with #bdNavbar to outrank the shared base rule at the top of this
-    // file, which sets the chevron to 1.5rem.
-    #bdNavbar .nav-hover-dropdown > .dropdown-toggle-split {
-      min-width: 1rem;
-      width: 1rem;
+    // The overlay must not paint its own hover background — the row already
+    // does. Without this the chevron reads as a separate control again, which
+    // is the whole defect. `!important` because the shared base block at the
+    // top of this file sets the chevron's own hover background with equal
+    // specificity and later source order.
+    #bdNavbar .nav-hover-dropdown > .dropdown-toggle-split:hover,
+    #bdNavbar .nav-hover-dropdown > .dropdown-toggle-split:focus-visible,
+    #bdNavbar .nav-hover-dropdown > .dropdown-toggle-split[aria-expanded="true"] {
+      background-color: transparent !important;
     }
   }
 
-  // Icon-only when the center track is too narrow even for bare labels
-  @container bd-nav (max-width: 40.99rem) {
+  // Icon-only when the center track cannot fit the icon+label row. The
+  // boundary is the complement of the tier above so the two tiers tile the
+  // whole range with no gap.
+  @container bd-nav (max-width: 50.99rem) {
     @include navbar-nav-icon-only;
   }
 }
@@ -681,7 +724,6 @@
       
       &:hover {
         background-color: var(--bs-tertiary-bg);
-        transform: rotate(90deg);
       }
       
       &:focus-visible {
@@ -768,20 +810,10 @@
   i {
     font-size: 1rem;
     width: 1.5rem;
-    transition: transform 0.15s ease-in-out;
   }
   
   &:hover {
     background-color: var(--bs-tertiary-bg);
-
-    // translateX widens overflow; desktop menus sit inside a clipped nav track
-    @media (max-width: 991.98px) {
-      transform: translateX(4px);
-    }
-
-    i {
-      transform: scale(1.1);
-    }
   }
   
   &:focus-visible {
@@ -1119,8 +1151,7 @@
     align-items: center;
 }
 
-#navbar .site-title-text,
-#navbar .site-subtitle-text {
+#navbar .site-title-text {
     display: inline-block;
 }
 
@@ -1157,9 +1188,28 @@
 
 // Desktop (lg+): 3-column grid — [brand/title | main nav | utilities] so nav cannot paint over Search/Settings
 @media (min-width: 992px) {
+    // Optical centering (#405) WITHOUT breaking the container queries.
+    //
+    // The obvious spelling — `1fr auto 1fr` — is a trap here. Track 2 must stay
+    // a `1fr` (a DEFINITE width): `.bd-navbar-nav-viewport` inside it is
+    // `width: 100%` + `container-type: inline-size`, and that percentage only
+    // resolves against a definite track. Make track 2 `auto` and it becomes
+    // content-sized, size containment hands `bd-nav` a degenerate width, and
+    // EVERY `@container bd-nav` label tier stops firing — the bar collapses to
+    // icon-only at all widths, which is the opposite of what #405 is for.
+    //
+    // So the nav keeps the elastic middle track and the two side tracks are
+    // equalised instead, via a shared floor. Whenever the brand and the
+    // utility cluster both fit inside it (the common case), the side tracks
+    // are the same width and the menubar is centred in the bar, not merely
+    // centred in its own track. The floor is deliberately small so it never
+    // steals the width the label tier needs at 1280px.
     #navbar .navbar-main {
         display: grid !important;
-        grid-template-columns: minmax(0, auto) minmax(0, 1fr) auto;
+        grid-template-columns:
+            minmax(var(--zer0-navbar-side-min, 9rem), auto)
+            minmax(0, 1fr)
+            minmax(var(--zer0-navbar-side-min, 9rem), auto);
         align-items: center;
         column-gap: 0.75rem;
         row-gap: 0.25rem;
@@ -1228,8 +1278,7 @@
         display: none;
     }
 
-    #navbar .site-title,
-    #navbar .site-subtitle {
+    #navbar .site-title {
         flex-shrink: 1;
         min-width: 0;
     }
@@ -1247,15 +1296,6 @@
         max-width: none;
     }
 
-    #navbar .site-subtitle .site-subtitle-text {
-        overflow: hidden;
-        text-overflow: ellipsis;
-        white-space: nowrap;
-        display: inline-block;
-        vertical-align: bottom;
-        max-width: none;
-    }
-
     // Progressive brand degradation (container width, not viewport).
     // The home-link icons add ~108px to the brand cluster, so they only appear
     // once the bar is wide enough to carry them AND the full menubar
@@ -1267,12 +1307,6 @@
         }
     }
 
-    @container navbar-main (max-width: 68rem) {
-        #navbar .site-subtitle {
-            display: none !important;
-        }
-    }
-
     @container navbar-main (max-width: 50rem) {
         #navbar .site-title .site-title-text {
             max-width: 100%;
@@ -1338,6 +1372,19 @@
         height: 2.5rem;
     }
 
+    // The square above is for BARE-GLYPH togglers. The labelled menu toggle
+    // (#405) also carries a "Menu" span, and 2.5rem cannot hold glyph + gap +
+    // label — the text would escape the button box and push the page past the
+    // viewport at every width below lg, which is exactly what makes a
+    // fixed-top bar read as "cut off". `.navbar-toggler-labeled`'s own
+    // `width: auto` loses to the ID selector above on specificity (0,2,0 vs
+    // 1,1,0); re-assert it here, where it outranks.
+    #navbar .navbar-toggler.navbar-toggler-labeled {
+        width: auto;
+        min-width: 2.5rem;
+        flex-shrink: 0;
+    }
+
     #navbar .nav-search-button {
         width: 2.5rem;
         height: 2.5rem;

data/_sass/core/_sidebar-extras.scss

@@ -20,20 +20,8 @@
 
 // MOVED → _sass/layouts/_navbar-extras.scss (token-aware FAB stacking)
 // MOVED → _sass/components/_cookie-banner.scss (token-aware, dark-mode-safe)
-// Retained shim: keep stacked-button responsive sizing inside the banner
-// because it is a banner-internal concern, not a banner-shell concern.
-.cookie-consent-banner {
-    @media (max-width: 768px) {
-        .btn {
-            width: 100%;
-            margin-bottom: 0.5rem;
-
-            &:last-child {
-                margin-bottom: 0;
-            }
-        }
-    }
-}
+// The banner's internal layout (formerly a full-width stacked-button shim
+// here) lives with the shell in _sass/components/_cookie-banner.scss.
 
 // Active TOC link highlighting
 .bd-toc nav a.active {

data/_sass/core/code-copy.scss

@@ -357,14 +357,33 @@ pre.highlight > button:focus {
   opacity: 1;
 }
 
-.button,
-button:not(.copy) {
-  display: inline-block;
-  padding: 0 20px;
-  border-radius: 4px;
-  border: 1px solid #bbb;
-  font-size: 11px;
-  cursor: pointer;
+// Extra actions inside a code block — SCOPED TO THIS COMPONENT (#412).
+//
+// This block used to read `.button, button:not(.copy)` with no scope at all.
+// An element selector in a component partial is a site-wide rule: it restyled
+// EVERY button on a consumer site that was not the theme's own copy button —
+// `padding: 0 20px`, `font-size: 11px`, and a hardcoded `#bbb` border that
+// bypassed the design tokens entirely. At specificity (0,1,1) it also outranked
+// `.btn` and any consumer's own `.my-button`, so escaping it meant a
+// specificity fight rather than a cascade (it-journey#634 had to scope to
+// `.code-block-header .itj-clip-btn` to win). A component partial styles its
+// own component and nothing else.
+//
+// The rule is kept, not deleted: a consumer that adds an action to the header
+// (see the `zer0:code-block-ready` contract in assets/js/code-copy.js) should
+// inherit the copy button's shape instead of arriving unstyled. Values are
+// tokens now, so a skin moves them.
+.code-block-header,
+pre.highlight {
+  > .button,
+  > button:not(.copy) {
+    display: inline-block;
+    padding: 0 var(--zer0-space-3);
+    border-radius: var(--zer0-radius-sm);
+    border: 1px solid var(--zer0-color-border);
+    font-size: var(--zer0-text-sm);
+    cursor: pointer;
+  }
 }
 
 // Non-highlight fenced code blocks

data/_sass/layouts/_navbar-extras.scss

@@ -53,13 +53,18 @@
       display: block;
     }
 
+    // No transform on :hover — a lift moves the FAB out from under a pointer
+    // parked on its bottom edge, hover exits, it drops back: infinite flicker.
+    // These are `.btn`s, so the 2px lift _ui-enhancements.scss puts on every
+    // button has to be cancelled explicitly, not merely not-added here.
     &:hover,
     &:focus-visible {
-      transform: translateY(-1px);
+      transform: none;
     }
 
+    // :active is safe, because the button is held down for its whole duration.
     &:active {
-      transform: translateY(0);
+      transform: translateY(1px);
     }
   }
 }
@@ -112,13 +117,18 @@
       display: block;
     }
 
+    // No transform on :hover — a lift moves the FAB out from under a pointer
+    // parked on its bottom edge, hover exits, it drops back: infinite flicker.
+    // These are `.btn`s, so the 2px lift _ui-enhancements.scss puts on every
+    // button has to be cancelled explicitly, not merely not-added here.
     &:hover,
     &:focus-visible {
-      transform: translateY(-1px);
+      transform: none;
     }
 
+    // :active is safe, because the button is held down for its whole duration.
     &:active {
-      transform: translateY(0);
+      transform: translateY(1px);
     }
   }
 }

data/assets/css/extension-points-demo.css

@@ -0,0 +1,27 @@
+/* ==========================================================================
+   extension-points-demo.css — a live consumer of the per-page `styles:` hook
+   ==========================================================================
+
+   Loaded ONLY by /docs/customization/extension-points/, through that page's
+   `styles:` frontmatter. Its job is to prove the hook works and to mark the
+   demo action button so the page's own prose can point at it.
+
+   Note what it does NOT have to do: fight a specificity war. Before #412,
+   `_sass/core/code-copy.scss` shipped a bare `button:not(.copy)` rule at
+   specificity (0,1,1), which outranked any single class a consumer could
+   write — so downstream code had to scope to `.code-block-header .my-btn`
+   just to set its own padding. That rule is scoped to the component now, and
+   a plain class is enough again.
+   ========================================================================== */
+
+.zer0-demo-action {
+  background: transparent;
+  color: var(--zer0-color-text-muted);
+  font-family: var(--zer0-font-mono);
+  line-height: 1.8;
+}
+
+.zer0-demo-action:hover,
+.zer0-demo-action:focus-visible {
+  color: inherit;
+}

data/assets/css/main.scss

@@ -44,6 +44,7 @@
 @import "components/book";
 @import "components/recipe";
 @import "components/setup-wizard";
+@import "components/mermaid";
 
 // 6. Layout partials
 @import "layouts/landing";

data/assets/data/wiki-index.json

@@ -142,11 +142,30 @@ sitemap: false
         {%- endif -%}
       {%- endfor -%}
       {%- assign outgoing = outgoing | uniq -%}
+      {%- comment -%}
+        `lastmod` and `description` (#412) — both already on `doc` in this loop,
+        so neither costs a new traversal. A notes/library UI needs them:
+        `lastmod` to sort by recency or show staleness, and `description`
+        because `excerpt` is body-derived while `description` is the AUTHORED
+        subtitle, which is the better card line whenever it exists.
+
+        Source order for the date follows the rest of the theme
+        (_includes/core/head.html, _layouts/article.html): `last_modified_at`,
+        then `lastmod`, then the document's own `date`. Emitted as ISO-8601 via
+        `date_to_xmlschema` so a consumer can sort strings without parsing.
+        Both keys are always present and always defined — `null` when the
+        document carries neither — rather than being conditionally omitted,
+        because a key that sometimes disappears is a worse contract than one
+        that is sometimes null.
+      {%- endcomment -%}
+      {%- assign doc_lastmod = doc.last_modified_at | default: doc.lastmod | default: doc.date -%}
       {
         "title": {{ doc.title | default: basename | jsonify }},
         "basename": {{ basename | jsonify }},
         "url": {{ doc.url | jsonify }},
         "collection": {{ doc.collection | default: nil | jsonify }},
+        "lastmod": {% if doc_lastmod %}{{ doc_lastmod | date_to_xmlschema | jsonify }}{% else %}null{% endif %},
+        "description": {{ doc.description | default: nil | jsonify }},
         "tags": {{ doc.tags | default: empty | jsonify }},
         "categories": {{ doc.categories | default: empty | jsonify }},
         "aliases": {{ aliases | jsonify }},