jekyll-theme-zer0 0.15.2 → 0.17.0

data/_data/navigation/README.md

@@ -0,0 +1,54 @@
+# Navigation Data Schema Documentation
+# ===================================
+#
+# This directory contains YAML navigation data files used by the sidebar
+# and navbar components. All files follow a standardized schema.
+#
+# ## Schema Definition
+#
+# Each navigation item can have the following properties:
+#
+# ```yaml
+# - title: string        # Required - Display text
+#   url: string          # Optional - Link URL (relative to site root)
+#   icon: string         # Optional - Bootstrap Icons class (e.g., "bi-folder")
+#   description: string  # Optional - Tooltip or description text
+#   expanded: boolean    # Optional - Default expanded state (default: false)
+#   children: array      # Optional - Nested navigation items (recursive)
+# ```
+#
+# ## Navigation Modes
+#
+# The sidebar supports three navigation modes set via `page.sidebar.nav`:
+#
+# 1. **auto** - Auto-generates from collection documents
+# 2. **tree** - Uses YAML data from this directory
+# 3. **categories** - Groups by Jekyll categories
+#
+# ## Available Files
+#
+# - main.yml      - Primary site navigation (navbar)
+# - docs.yml      - Documentation section navigation
+# - about.yml     - About section navigation
+# - quickstart.yml - Quick start guide navigation
+# - home.yml      - Homepage quick links
+# - posts.yml     - Blog category navigation
+#
+# ## Example Usage
+#
+# In page front matter:
+# ```yaml
+# sidebar:
+#   nav: docs  # Uses _data/navigation/docs.yml
+# ```
+#
+# ## Schema Validation
+#
+# Navigation YAML is validated at build time by _plugins/navigation_validator.rb
+# Invalid schemas will produce build warnings.
+#
+# ## Migration Notes (v2.0)
+#
+# - Renamed `sublinks` to `children` for consistency with tree terminology
+# - Added `expanded` property for default state
+# - Navigation modes changed: dynamic→auto, searchCats→categories

data/_data/navigation/about.yml

@@ -1,11 +1,13 @@
 # About Navigation Configuration
-# Used by: About section sidebar and related pages
+# Used by: About section sidebar (nav: tree)
 # Purpose: Navigation for about pages, features, settings, and site info
+# Schema: See README.md for full documentation
 
 - title: About
   icon: bi-info-circle
   url: /about/
-  sublinks:
+  expanded: true
+  children:
     - title: Overview
       url: /about/
     - title: Features
@@ -16,7 +18,7 @@
 - title: Site Info
   icon: bi-bar-chart
   url: /about/stats/
-  sublinks:
+  children:
     - title: Statistics
       url: /about/stats/
     - title: Site Map
@@ -27,14 +29,14 @@
 - title: Settings
   icon: bi-gear
   url: /about/config/
-  sublinks:
+  children:
     - title: Configuration
       url: /about/config/
 
 - title: Legal
   icon: bi-file-text
   url: /terms-of-service/
-  sublinks:
+  children:
     - title: Terms of Service
       url: /terms-of-service/
     - title: Privacy Policy

data/_data/navigation/docs.yml

@@ -1,57 +1,103 @@
 # Documentation Navigation Configuration
-# Used by: Docs sidebar and documentation pages
-# Purpose: Organize documentation by topic area
+# Used by: Docs sidebar (nav: tree)
+# Purpose: Organize documentation by topic area for _docs collection
+# Schema: See README.md for full documentation
 
+# ============================================================
+# Getting Started
+# ============================================================
+- title: Getting Started
+  icon: bi-rocket-takeoff
+  url: /docs/
+  expanded: true
+  children:
+    - title: Documentation Home
+      url: /docs/
+    - title: Installation
+      url: /docs/installation/
+    - title: Troubleshooting
+      url: /docs/troubleshooting/
+
+# ============================================================
+# Core Technologies
+# ============================================================
 - title: Jekyll
   icon: bi-journal-code
   url: /docs/jekyll/
-  sublinks:
-    - title: Jekyll Guide
+  children:
+    - title: Jekyll Overview
       url: /docs/jekyll/
-    - title: Mermaid Diagrams
-      url: /docs/jekyll/mermaid-native-markdown/
-    - title: Math with MathJax
-      url: /docs/jekyll/jekyll-math-symbols-with-mathjax/
+    - title: Configuration
+      url: /docs/jekyll/jekyll-config/
+    - title: Front Matter
+      url: /docs/front-matter/
     - title: Liquid Templating
       url: /docs/jekyll/jekyll-liquid/
-    - title: Frontmatter CMS
-      url: /docs/jekyll/jekyll-frontmatter-cms/
     - title: Syntax Highlighting
       url: /docs/jekyll/jekyll-highlighting/
+    - title: Performance
+      url: /docs/jekyll/jekyll-performance-optimization/
+    - title: Security
+      url: /docs/jekyll/jekyll-security/
+
+- title: Ruby & Bundler
+  icon: bi-gem
+  url: /docs/ruby/
+  children:
+    - title: Ruby Overview
+      url: /docs/ruby/
+    - title: Ruby 101
+      url: /docs/ruby-101/
+
+- title: Liquid
+  icon: bi-droplet
+  url: /docs/liquid/
+  children:
+    - title: Liquid Overview
+      url: /docs/liquid/
 
+- title: Docker
+  icon: bi-box-seam
+  url: /docs/docker/
+  children:
+    - title: Docker Overview
+      url: /docs/docker/
+
+- title: Bootstrap
+  icon: bi-bootstrap
+  url: /docs/bootstrap/
+  children:
+    - title: Bootstrap Overview
+      url: /docs/bootstrap/
+
+# ============================================================
+# Theme Features
+# ============================================================
 - title: Features
   icon: bi-stars
-  url: /about/features/
-  sublinks:
+  url: /features/
+  children:
     - title: All Features
-      url: /about/features/
+      url: /features/
+    - title: Mermaid Diagrams
+      url: /docs/jekyll/mermaid-native-markdown/
+    - title: Math with MathJax
+      url: /docs/jekyll/jekyll-math-symbols-with-mathjax/
     - title: Preview Image Generator
       url: /docs/features/preview-image-generator/
-    - title: Statistics Dashboard
-      url: /about/features/statistics-dashboard/
-    - title: AI Development Guide
-      url: /about/features/ai-development-guide/
+    - title: Frontmatter CMS
+      url: /docs/jekyll/jekyll-frontmatter-cms/
 
+# ============================================================
+# Deployment
+# ============================================================
 - title: Deployment
   icon: bi-cloud-upload
   url: /quickstart/github-setup/
-  sublinks:
+  children:
     - title: GitHub Pages
       url: /quickstart/github-setup/
     - title: Netlify
       url: /docs/jekyll/deploying-jekyll-website-to-netlify/
     - title: Custom Domain
       url: /docs/jekyll/deploying-personal-website-with-custom-domain/
-
-- title: Configuration
-  icon: bi-gear
-  url: /about/config/
-  sublinks:
-    - title: Site Config
-      url: /about/config/
-    - title: Jekyll Config
-      url: /docs/jekyll/jekyll-config/
-    - title: Performance
-      url: /docs/jekyll/jekyll-performance-optimization/
-    - title: Security
-      url: /docs/jekyll/jekyll-security/

data/_data/navigation/home.yml

@@ -1,11 +1,12 @@
 # Home Navigation Configuration
 # Used by: Header navigation and homepage quick links
 # Purpose: Quick access links for the home/landing area
+# Schema: See README.md for full documentation
 
 - title: Home
   icon: bi-house
   url: /
-  sublinks:
+  children:
     - title: Blog
       url: /blog/
     - title: Quick Start
@@ -14,7 +15,7 @@
 - title: Discover
   icon: bi-compass
   url: /sitemap/
-  sublinks:
+  children:
     - title: Site Map
       url: /sitemap/
     - title: Categories
@@ -25,7 +26,7 @@
 - title: Connect
   icon: bi-envelope
   url: /contact/
-  sublinks:
+  children:
     - title: Contact
       url: /contact/
     - title: About

data/_data/navigation/main.yml

@@ -1,11 +1,12 @@
 # Main Navigation Configuration
 # Used by: _includes/navigation/navbar.html
-# Purpose: Primary site navigation with dropdown sublinks
+# Purpose: Primary site navigation with dropdown children
+# Schema: See README.md for full documentation
 
 - title: Quick Start
   icon: bi-rocket-takeoff
   url: /quickstart/
-  sublinks:
+  children:
     - title: Machine Setup
       url: /quickstart/machine-setup/
     - title: Jekyll Setup
@@ -16,7 +17,7 @@
 - title: Blog
   icon: bi-journal-text
   url: /blog/
-  sublinks:
+  children:
     - title: All Posts
       url: /posts/
     - title: Categories
@@ -27,18 +28,26 @@
 - title: Docs
   icon: bi-journal-bookmark
   url: /docs/
-  sublinks:
+  children:
+    - title: Documentation Home
+      url: /docs/
+    - title: Installation
+      url: /docs/installation/
     - title: Jekyll Guide
       url: /docs/jekyll/
+    - title: Docker
+      url: /docs/docker/
     - title: Features
-      url: /about/features/
+      url: /features/
+    - title: Troubleshooting
+      url: /docs/troubleshooting/
 
 - title: About
   icon: bi-info-circle
   url: /about/
-  sublinks:
+  children:
     - title: Features
-      url: /about/features/
+      url: /features/
     - title: Statistics
       url: /about/stats/
     - title: Config

data/_data/navigation/quickstart.yml

@@ -1,12 +1,14 @@
 # Quick Start Navigation Configuration
-# Used by: Quick Start sidebar and related pages
+# Used by: Quick Start sidebar (nav: tree)
 # Purpose: Step-by-step guide navigation for new users
 # Order: Overview → Machine → Jekyll → GitHub → Personalization
+# Schema: See README.md for full documentation
 
 - title: "Quick Start"
   icon: bi-flag
   url: /quickstart/
-  sublinks:
+  expanded: true
+  children:
     - title: "1. Machine Setup"
       url: /quickstart/machine-setup/
       icon: bi-laptop

data/_includes/components/js-cdn.html

@@ -28,5 +28,5 @@
         integrity="sha384-YvpcrYf0tY3lHB60NNkmXc5s9fDVZLESaAA55NDzOxhy9GkcIdslK1eN7N6jIeHz" 
         crossorigin="anonymous"></script>
 
-<!-- Sidebar Navigation Enhancements - Deferred for performance -->
-<script defer src="{{ '/assets/js/sidebar.js' | relative_url }}"></script>
+<!-- Navigation ES6 Modules - Enhanced sidebar, scroll spy, keyboard shortcuts, gestures -->
+<script type="module" src="{{ '/assets/js/modules/navigation/index.js' | relative_url }}"></script>

data/_includes/components/preview-image.html

@@ -9,8 +9,12 @@
        style="height: 180px; object-fit: cover;" 
     -%}
   
-  Convention: All preview paths should be absolute (e.g., /assets/images/preview.png)
-  External URLs (https://...) are also supported.
+  Convention: Preview paths can omit the /assets/ prefix.
+  The component will auto-prepend the assets_prefix from _config.yml.
+  Examples:
+    - /images/previews/my-image.png → /assets/images/previews/my-image.png
+    - /assets/images/previews/my-image.png → unchanged
+    - https://example.com/image.png → unchanged (external URL)
 {% endcomment %}
 {% assign img = include.src | default: site.teaser %}
 {% assign alt = include.alt | default: "Preview image" %}
@@ -18,9 +22,22 @@
 {% assign style = include.style %}
 {% assign loading = include.loading | default: "lazy" %}
 
-{% comment %} External URL or internal path {% endcomment %}
+{% comment %} Get assets prefix configuration {% endcomment %}
+{% assign assets_prefix = site.preview_images.assets_prefix | default: '/assets' %}
+{% assign auto_prefix = site.preview_images.auto_prefix | default: true %}
+
+{% comment %} Determine final image source {% endcomment %}
 {% if img contains '://' %}
+  {% comment %} External URL - use as-is {% endcomment %}
   {% assign final_src = img %}
+{% elsif auto_prefix and img != blank %}
+  {% comment %} Check if path already has the assets prefix {% endcomment %}
+  {% if img contains assets_prefix %}
+    {% assign final_src = img | relative_url %}
+  {% else %}
+    {% comment %} Prepend assets prefix to the path {% endcomment %}
+    {% assign final_src = assets_prefix | append: img | relative_url %}
+  {% endif %}
 {% else %}
   {% assign final_src = img | relative_url %}
 {% endif %}

data/_includes/content/intro.html

@@ -16,12 +16,21 @@
 <!-- Intro Section -->
 
 {% comment %}
-  Determine the preview image path. All preview paths should be absolute
-  starting with /assets/ or external URLs starting with ://
+  Determine the preview image path. Preview paths can omit the /assets/ prefix.
+  The component will auto-prepend the assets_prefix from _config.yml.
 {% endcomment %}
 {% assign preview_image = page.preview | default: site.info_banner %}
+{% assign assets_prefix = site.preview_images.assets_prefix | default: '/assets' %}
+{% assign auto_prefix = site.preview_images.auto_prefix | default: true %}
+
 {% if preview_image contains '://' %}
   {% assign preview_path = preview_image %}
+{% elsif auto_prefix and preview_image != blank %}
+  {% if preview_image contains assets_prefix %}
+    {% assign preview_path = preview_image | relative_url %}
+  {% else %}
+    {% assign preview_path = assets_prefix | append: preview_image | relative_url %}
+  {% endif %}
 {% else %}
   {% assign preview_path = preview_image | relative_url %}
 {% endif %}

data/_includes/content/seo.html

@@ -23,8 +23,19 @@
 {%- assign page_large_image = page.header.og_image | default: page.header.overlay_image | default: page.header.image | absolute_url -%}
 {%- assign page_large_image = page_large_image | escape -%}
 
+{%- comment -%} Handle preview image with configurable assets prefix {%- endcomment -%}
 {%- assign page_teaser_image = page.preview | default: site.og_image -%}
-{%- assign page_teaser_image = {{ site.public_folder }}/page_teaser_image | escape -%}
+{%- assign assets_prefix = site.preview_images.assets_prefix | default: '/assets' -%}
+{%- assign auto_prefix = site.preview_images.auto_prefix | default: true -%}
+
+{%- if page_teaser_image contains '://' -%}
+  {%- comment -%} External URL - use as-is {%- endcomment -%}
+{%- elsif auto_prefix and page_teaser_image != blank -%}
+  {%- unless page_teaser_image contains assets_prefix -%}
+    {%- assign page_teaser_image = assets_prefix | append: page_teaser_image -%}
+  {%- endunless -%}
+{%- endif -%}
+{%- assign page_teaser_image = page_teaser_image | absolute_url | escape -%}
 
 {%- assign site_og_image = site.og_image | absolute_url -%}
 {%- assign site_og_image = site_og_image | escape -%}

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

@@ -8,7 +8,7 @@
       <div class="card-body p-4 d-flex flex-column text-center">
         <p class="card-text mb-3">Install the theme as a Ruby gem for classic Jekyll workflows.</p>
         <pre class="bg-dark text-light p-3 rounded mb-3 small text-start overflow-auto"><code>gem install {{ site.resources.rubygems.name | default: 'zer0-mistakes' }}</code></pre>
-        <a class="btn btn-outline-primary btn-sm mt-auto" href="{{ site.resources.rubygems.url | default: '#' }}" target="_blank" rel="noopener">View on RubyGems</a>
+        <a class="btn btn-outline-primary btn-sm mt-auto" href="{{ site.resources.rubygems.url | default: '' | join: '' | default: '#' }}" target="_blank" rel="noopener">View on RubyGems</a>
       </div>
     </div>
   </div>
@@ -20,9 +20,9 @@
       </div>
       <div class="card-body p-4 d-flex flex-column text-center">
         <p class="card-text mb-3">Run locally with zero Ruby setup using Docker.</p>
-        <pre class="bg-dark text-light p-3 rounded mb-3 small text-start overflow-auto"><code>docker pull {{ site.resources.docker.image | default: 'bamr87/zer0-mistakes' }}
-docker run -p 4000:4000 {{ site.resources.docker.image | default: 'bamr87/zer0-mistakes' }}</code></pre>
-        <a class="btn btn-outline-info btn-sm mt-auto" href="{{ site.resources.docker.hub_url | default: '#' }}" target="_blank" rel="noopener">View on Docker Hub</a>
+        <pre class="bg-dark text-light p-3 rounded mb-3 small text-start overflow-auto"><code>docker pull {{ site.resources.docker.image | default: '' | join: '' | default: 'bamr87/zer0-mistakes' }}
+docker run -p 4000:4000 {{ site.resources.docker.image | default: '' | join: '' | default: 'bamr87/zer0-mistakes' }}</code></pre>
+        <a class="btn btn-outline-info btn-sm mt-auto" href="{{ site.resources.docker.hub_url | default: '' | join: '' | default: '#' }}" target="_blank" rel="noopener">View on Docker Hub</a>
       </div>
     </div>
   </div>
@@ -34,11 +34,11 @@ docker run -p 4000:4000 {{ site.resources.docker.image | default: 'bamr87/zer0-m
       </div>
       <div class="card-body p-4 d-flex flex-column text-center">
         <p class="card-text mb-3">Improve the theme by forking the repo and opening a PR.</p>
-        <pre class="bg-dark text-light p-3 rounded mb-3 small text-start overflow-auto"><code>git clone {{ site.resources.github_repo | default: site.github.repository_url }}
+        <pre class="bg-dark text-light p-3 rounded mb-3 small text-start overflow-auto"><code>git clone {{ site.resources.github_repo | default: '' | join: '' | default: site.github.repository_url }}
 cd {{ site.local_repo | default: site.repository_name | default: 'repo' }}
-git remote add upstream {{ site.resources.github_repo | default: site.github.repository_url }}
+git remote add upstream {{ site.resources.github_repo | default: '' | join: '' | default: site.github.repository_url }}
 git checkout -b feature/your-change</code></pre>
-  <a class="btn btn-outline-secondary btn-sm mt-auto" href="{{ site.resources.github_fork | default: site.github.repository_url | append: '/fork' }}" target="_blank" rel="noopener">Fork on GitHub</a>
+  <a class="btn btn-outline-secondary btn-sm mt-auto" href="{{ site.resources.github_fork | default: '' | join: '' | default: site.github.repository_url | append: '/fork' }}" target="_blank" rel="noopener">Fork on GitHub</a>
       </div>
     </div>
   </div>
@@ -46,7 +46,7 @@ git checkout -b feature/your-change</code></pre>
 
 <!-- Contributing guide call-to-action placed below all cards -->
 <div class="text-center mt-4">
-  <a class="btn btn-outline-secondary" href="{{ site.resources.contributing | default: '#' }}" target="_blank" rel="noopener">
+  <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
   </a>
 </div>

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

@@ -3,22 +3,22 @@
   <div class="container-xl px-4 px-md-5">
     <div class="row g-3 justify-content-center text-center align-items-center">
       <div class="col-6 col-md-3 d-flex justify-content-center">
-        <a class="btn btn-outline-light btn-sm w-100" href="{{ site.resources.github_repo | default: site.github.repository_url | default: '/' }}" target="_blank" rel="noopener">
+        <a class="btn btn-outline-light btn-sm w-100" href="{{ site.resources.github_repo | default: '' | join: '' | default: site.github.repository_url | default: '/' }}" target="_blank" rel="noopener">
           <i class="bi bi-github me-2"></i> GitHub
         </a>
       </div>
       <div class="col-6 col-md-3 d-flex justify-content-center">
-        <a class="btn btn-outline-light btn-sm w-100" href="{{ site.resources.rubygems.url | default: '#' }}" target="_blank" rel="noopener">
+        <a class="btn btn-outline-light btn-sm w-100" href="{{ site.resources.rubygems.url | default: '' | join: '' | default: '#' }}" target="_blank" rel="noopener">
           <i class="bi bi-gem me-2"></i> RubyGems
         </a>
       </div>
       <div class="col-6 col-md-3 d-flex justify-content-center">
-        <a class="btn btn-outline-light btn-sm w-100" href="{{ site.resources.docker.hub_url | default: '#' }}" target="_blank" rel="noopener">
+        <a class="btn btn-outline-light btn-sm w-100" href="{{ site.resources.docker.hub_url | default: '' | join: '' | default: '#' }}" target="_blank" rel="noopener">
           <i class="bi bi-box-seam me-2"></i> Docker Hub
         </a>
       </div>
       <div class="col-6 col-md-3 d-flex justify-content-center">
-        <a class="btn btn-outline-light btn-sm w-100" href="{{ site.resources.github_fork | default: site.github.repository_url | append: '/fork' }}" target="_blank" rel="noopener">
+        <a class="btn btn-outline-light btn-sm w-100" href="{{ site.resources.github_fork | default: '' | join: '' | default: site.github.repository_url | append: '/fork' }}" target="_blank" rel="noopener">
           <i class="bi bi-git me-2"></i> Fork Project
         </a>
       </div>

data/_includes/navigation/breadcrumbs.html

@@ -10,14 +10,37 @@
   <ol itemscope itemtype="https://schema.org/BreadcrumbList">
     <i class="bi bi-folder"></i>
     {% assign crumbs = page.url | remove:'/index.html' | split: '/' %}
-    <a href="/">root</a>
-    {% for crumb in crumbs offset: 1 %}
-    {% if forloop.last %}
-    / {{ page.title }}
+    {% assign section = crumbs[1] | default: '' %}
+    <a href="{{ '/' | relative_url }}">root</a>
+
+    {% comment %}
+      Avoid linking to intermediate directories that don't have index pages.
+      Example: posts are /posts/YYYY/MM/DD/slug/ (only /posts/ and the leaf page exist).
+    {% endcomment %}
+    {% if section == 'posts' %}
+      / <a href="{{ '/posts/' | relative_url }}">Posts</a>
+      / {{ page.title }}
+    {% elsif section == 'notebooks' %}
+      / <a href="{{ '/notebooks/' | relative_url }}">Notebooks</a>
+      / {{ page.title }}
+    {% elsif section == 'notes' %}
+      / <a href="{{ '/notes/' | relative_url }}">Notes</a>
+      / {{ page.title }}
+    {% elsif section == 'docs' %}
+      / <a href="{{ '/docs/' | relative_url }}">Docs</a>
+      / {{ page.title }}
     {% else %}
-    / <a href="{% assign crumb_limit = forloop.index | plus: 1 %}{% for crumb in crumbs limit: crumb_limit %}{{ crumb | append: '/' }}{% endfor %}">{{ crumb | replace:'-',' ' | remove:'.html' | capitalize }}</a>
+      {% for crumb in crumbs offset: 1 %}
+        {% if forloop.last %}
+          / {{ page.title }}
+        {% elsif forloop.first %}
+          / <a href="{{ '/' | append: crumb | append: '/' | relative_url }}">{{ crumb | replace:'-',' ' | remove:'.html' | capitalize }}</a>
+        {% else %}
+          {% comment %} Keep intermediate crumbs as plain text to avoid dead links {% endcomment %}
+          / {{ crumb | replace:'-',' ' | remove:'.html' | capitalize }}
+        {% endif %}
+      {% endfor %}
     {% endif %}
-    {% endfor %}
   </ol>
 </nav>
 <!-- Secret Search bar  -->