jekyll-theme-zer0 0.22.0 → 0.22.19

data/_includes/components/feature-card.html

@@ -0,0 +1,94 @@
+<!--
+  ===================================================================
+  FEATURE CARD - Data-driven feature display from features.yml
+  ===================================================================
+
+  File: feature-card.html
+  Path: _includes/components/feature-card.html
+  Purpose: Reusable card component that renders a single feature from
+           the _data/features.yml registry. Used by the features page,
+           news index, documentation, and any page that needs to
+           display feature information consistently.
+
+  Parameters:
+  - feature  (hash)   : A single feature object from site.data.features.features (required)
+  - style    (string) : Card border color class — "primary", "success", "info", etc. (optional, default: none)
+  - icon     (string) : Bootstrap Icon class, e.g. "bi-rocket-takeoff" (optional, default: "bi-check-circle-fill")
+  - icon_color (string): Icon text-color class, e.g. "text-success" (optional, default: "text-success")
+  - show_refs (bool)  : Show file references list (optional, default: false)
+  - compact  (bool)   : Compact mode — hides sub-features list (optional, default: false)
+  - features_limit (int) : Max sub-features shown in the list (optional, default: 5)
+
+  Usage:
+    {% assign f = site.data.features.features | where: "id", "ZER0-001" | first %}
+    {% include components/feature-card.html feature=f style="primary" icon="bi-bootstrap" icon_color="text-primary" %}
+  ===================================================================
+-->
+{% assign f = include.feature %}
+{% assign border = include.style %}
+{% assign icon = include.icon | default: "bi-check-circle-fill" %}
+{% assign icon_color = include.icon_color | default: "text-success" %}
+{% assign show_refs = include.show_refs | default: false %}
+{% assign compact = include.compact | default: false %}
+{% assign features_limit = include.features_limit | default: 5 %}
+<div class="card h-100 {% unless border == blank %}border-{{ border }}{% endunless %}">
+  <div class="card-body">
+    <h5 class="card-title">
+      <i class="bi {{ icon }} {{ icon_color }} me-2"></i>
+      {{ f.title }}
+    </h5>
+    <p class="card-text">{{ f.description }}</p>
+
+    {% unless compact %}
+      {% if f.features %}
+      <div class="mt-3">
+        <h6 class="text-muted small">Key Features:</h6>
+        <ul class="small mb-0">
+          {% for item in f.features limit:features_limit %}
+          <li>{{ item }}</li>
+          {% endfor %}
+        </ul>
+      </div>
+      {% endif %}
+    {% endunless %}
+
+    {% if show_refs and f.references %}
+    <div class="mt-3">
+      <h6 class="text-muted small">References:</h6>
+      <ul class="small mb-0">
+        {% for ref in f.references %}
+          {% assign key = ref[0] %}
+          {% assign value = ref[1] %}
+          {% if value.first %}
+            {% for file in value %}
+            <li><code>{{ file }}</code></li>
+            {% endfor %}
+          {% else %}
+            <li><code>{{ value }}</code></li>
+          {% endif %}
+        {% endfor %}
+      </ul>
+    </div>
+    {% endif %}
+
+    <div class="mt-3">
+      <span class="badge bg-primary">{{ f.id }}</span>
+      <span class="badge bg-secondary">v{{ f.version }}</span>
+      {% for tag in f.tags limit:3 %}
+      <span class="badge bg-light text-dark">{{ tag }}</span>
+      {% endfor %}
+    </div>
+  </div>
+  {% if f.docs %}
+  <div class="card-footer">
+    <a href="{{ f.docs }}" class="btn btn-sm btn-outline-{% unless border == blank %}{{ border }}{% else %}primary{% endunless %}">
+      <i class="bi bi-book me-1"></i>Documentation
+    </a>
+    {% if f.link and f.link != "/" %}
+    <a href="{{ f.link }}" class="btn btn-sm btn-outline-secondary ms-1">
+      <i class="bi bi-box-arrow-up-right me-1"></i>Demo
+    </a>
+    {% endif %}
+  </div>
+  {% endif %}
+</div>

data/_includes/components/info-section.html

@@ -1,14 +1,14 @@
 <!--
   ===================================================================
-  INFO SECTION - Settings Modal with Tabbed Interface
+  INFO SECTION - Settings Offcanvas with Tabbed Interface
   ===================================================================
   
   File: info-section.html
   Path: _includes/components/info-section.html
-  Purpose: Unified settings modal with tabs for Settings, Environment, Developer
+  Purpose: Unified settings offcanvas panel with tabs for Settings, Environment, Developer
   
   Dependencies:
-  - Bootstrap 5 Modal, Tabs
+  - Bootstrap 5 Offcanvas, Tabs
   - _includes/components/env-switcher.html
   - _includes/components/theme-info.html
   - _includes/components/dev-shortcuts.html
@@ -16,167 +16,190 @@
   - _includes/navigation/breadcrumbs.html
   
   References:
-  - https://getbootstrap.com/docs/5.3/components/modal/
+  - https://getbootstrap.com/docs/5.3/components/offcanvas/
   - https://getbootstrap.com/docs/5.3/components/navs-tabs/
   ===================================================================
 -->
 
 {% include components/env-detect.html %}
-<!-- Settings Modal -->
-<div class="modal fade" id="info-section" tabindex="-1" aria-labelledby="infoSectionLabel" aria-hidden="true">
-  <div class="modal-dialog modal-dialog-centered modal-dialog-scrollable">
-    <div class="modal-content">
+<!-- Settings Offcanvas -->
+<div class="offcanvas offcanvas-end" tabindex="-1" id="info-section" aria-labelledby="infoSectionLabel">
+  
+  <!-- Offcanvas Header -->
+  <div class="offcanvas-header border-bottom pb-0 d-block">
+    <div class="d-flex align-items-center justify-content-between mb-2">
+      <h5 class="offcanvas-title" id="infoSectionLabel">
+        <i class="bi bi-gear-wide-connected me-2"></i>Settings
+      </h5>
+      <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
+    </div>
+    
+    <!-- Tab Navigation -->
+    <ul class="nav nav-tabs" id="infoTabs" role="tablist">
+      <li class="nav-item" role="presentation">
+        <button class="nav-link active" id="settings-tab" data-bs-toggle="tab" data-bs-target="#settings-pane" type="button" role="tab" aria-controls="settings-pane" aria-selected="true">
+          <i class="bi bi-sliders me-1"></i>
+          <span class="d-none d-sm-inline">Settings</span>
+        </button>
+      </li>
+      <li class="nav-item" role="presentation">
+        <button class="nav-link" id="environment-tab" data-bs-toggle="tab" data-bs-target="#environment-pane" type="button" role="tab" aria-controls="environment-pane" aria-selected="false">
+          <i class="bi bi-hdd-network me-1"></i>
+          <span class="d-none d-sm-inline">Environment</span>
+          {% if is_production %}
+            <span class="badge bg-success ms-1 d-none d-md-inline-block">Prod</span>
+          {% else %}
+            <span class="badge bg-warning text-dark ms-1 d-none d-md-inline-block">Dev</span>
+          {% endif %}
+        </button>
+      </li>
+      <li class="nav-item" role="presentation">
+        <button class="nav-link" id="developer-tab" data-bs-toggle="tab" data-bs-target="#developer-pane" type="button" role="tab" aria-controls="developer-pane" aria-selected="false">
+          <i class="bi bi-code-slash me-1"></i>
+          <span class="d-none d-sm-inline">Developer</span>
+        </button>
+      </li>
+      <li class="nav-item" role="presentation">
+        <button class="nav-link" id="background-tab" data-bs-toggle="tab" data-bs-target="#background-pane" type="button" role="tab" aria-controls="background-pane" aria-selected="false">
+          <i class="bi bi-palette2 me-1"></i>
+          <span class="d-none d-sm-inline">Background</span>
+        </button>
+      </li>
+    </ul>
+  </div>
+  
+  <!-- Offcanvas Body with Tab Content -->
+  <div class="offcanvas-body">
+    <div class="tab-content" id="infoTabContent">
       
-      <!-- Modal Header -->
-      <div class="modal-header border-bottom-0 pb-0">
-        <div class="w-100">
-          <div class="d-flex align-items-center justify-content-between mb-2">
-            <h5 class="modal-title" id="infoSectionLabel">
-              <i class="bi bi-gear-wide-connected me-2"></i>Settings
-            </h5>
-            <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
-          </div>
-          
-          <!-- Tab Navigation -->
-          <ul class="nav nav-tabs" id="infoTabs" role="tablist">
-            <li class="nav-item" role="presentation">
-              <button class="nav-link active" id="settings-tab" data-bs-toggle="tab" data-bs-target="#settings-pane" type="button" role="tab" aria-controls="settings-pane" aria-selected="true">
-                <i class="bi bi-sliders me-1"></i>
-                <span class="d-none d-sm-inline">Settings</span>
-              </button>
-            </li>
-            <li class="nav-item" role="presentation">
-              <button class="nav-link" id="environment-tab" data-bs-toggle="tab" data-bs-target="#environment-pane" type="button" role="tab" aria-controls="environment-pane" aria-selected="false">
-                <i class="bi bi-hdd-network me-1"></i>
-                <span class="d-none d-sm-inline">Environment</span>
-                {% if is_production %}
-                  <span class="badge bg-success ms-1 d-none d-md-inline-block">Prod</span>
-                {% else %}
-                  <span class="badge bg-warning text-dark ms-1 d-none d-md-inline-block">Dev</span>
-                {% endif %}
-              </button>
-            </li>
-            <li class="nav-item" role="presentation">
-              <button class="nav-link" id="developer-tab" data-bs-toggle="tab" data-bs-target="#developer-pane" type="button" role="tab" aria-controls="developer-pane" aria-selected="false">
-                <i class="bi bi-code-slash me-1"></i>
-                <span class="d-none d-sm-inline">Developer</span>
-              </button>
-            </li>
-          </ul>
+      <!-- Settings Tab -->
+      <div class="tab-pane fade show active" id="settings-pane" role="tabpanel" aria-labelledby="settings-tab" tabindex="0">
+        
+        <!-- Search -->
+        <div class="mb-4">
+          <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
+            <i class="bi bi-search me-1"></i>Search
+          </h6>
+          {% include components/searchbar.html %}
         </div>
-      </div>
-      
-      <!-- Modal Body with Tab Content -->
-      <div class="modal-body">
-        <div class="tab-content" id="infoTabContent">
-          
-          <!-- Settings Tab -->
-          <div class="tab-pane fade show active" id="settings-pane" role="tabpanel" aria-labelledby="settings-tab" tabindex="0">
-            
-            <!-- Search -->
-            <div class="mb-4">
-              <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
-                <i class="bi bi-search me-1"></i>Search
-              </h6>
-              {% include components/searchbar.html %}
-            </div>
-            
-            <!-- Theme Toggle -->
-            <div class="mb-4">
-              <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
-                <i class="bi bi-moon-stars me-1"></i>Appearance
-              </h6>
-              <div class="d-flex align-items-center justify-content-between p-3 bg-body-tertiary rounded">
-                <span>Theme Mode</span>
-                {% include components/halfmoon.html %}
-              </div>
-            </div>
-            
-            <!-- Theme Info (Collapsible) -->
-            <div class="mb-3">
-              <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
-                <i class="bi bi-info-circle me-1"></i>About
-              </h6>
-              <button class="btn btn-outline-secondary btn-sm w-100 d-flex justify-content-between align-items-center" type="button" data-bs-toggle="collapse" data-bs-target="#themeInfoCollapse" aria-expanded="false" aria-controls="themeInfoCollapse">
-                <span>Theme & Build Info</span>
-                <i class="bi bi-chevron-down"></i>
-              </button>
-              <div class="collapse mt-2" id="themeInfoCollapse">
-                {% include components/theme-info.html %}
-              </div>
-            </div>
+        
+        <!-- Theme Toggle -->
+        <div class="mb-4">
+          <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
+            <i class="bi bi-moon-stars me-1"></i>Appearance
+          </h6>
+          <div class="d-flex align-items-center justify-content-between p-3 bg-body-tertiary rounded">
+            <span>Theme Mode</span>
+            {% include components/halfmoon.html %}
           </div>
-          
-          <!-- Environment Tab -->
-          <div class="tab-pane fade" id="environment-pane" role="tabpanel" aria-labelledby="environment-tab" tabindex="0">
-            {% include components/env-switcher.html %}
+        </div>
+        
+        <!-- Theme Info (Collapsible) -->
+        <div class="mb-3">
+          <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
+            <i class="bi bi-info-circle me-1"></i>About
+          </h6>
+          <button class="btn btn-outline-secondary btn-sm w-100 d-flex justify-content-between align-items-center" type="button" data-bs-toggle="collapse" data-bs-target="#themeInfoCollapse" aria-expanded="false" aria-controls="themeInfoCollapse">
+            <span>Theme & Build Info</span>
+            <i class="bi bi-chevron-down"></i>
+          </button>
+          <div class="collapse mt-2" id="themeInfoCollapse">
+            {% include components/theme-info.html %}
           </div>
-          
-          <!-- Developer Tab -->
-          <div class="tab-pane fade" id="developer-pane" role="tabpanel" aria-labelledby="developer-tab" tabindex="0">
-            
-            <!-- Page Location -->
-            <div class="mb-4">
-              <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
-                <i class="bi bi-signpost-split me-1"></i>Page Location
-              </h6>
-              {% include navigation/breadcrumbs.html %}
-            </div>
-            
-            <!-- Source Code Shortcuts -->
-            <div class="mb-4">
-              <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
-                <i class="bi bi-code-square me-1"></i>Source Code
-              </h6>
-              {% include components/dev-shortcuts.html %}
-            </div>
-            
-            <!-- Page Metadata -->
-            <div class="mb-3">
-              <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
-                <i class="bi bi-file-earmark-code me-1"></i>Page Info
-              </h6>
-              <div class="table-responsive">
-                <table class="table table-sm table-hover mb-0 small">
-                  <tbody>
-                    <tr>
-                      <td class="text-body-secondary" style="width: 30%;">Layout</td>
-                      <td><code>{{ page.layout | default: "none" }}</code></td>
-                    </tr>
-                    <tr>
-                      <td class="text-body-secondary">Collection</td>
-                      <td><code>{{ page.collection | default: "none" }}</code></td>
-                    </tr>
-                    <tr>
-                      <td class="text-body-secondary">Path</td>
-                      <td><code class="text-break">{{ page.path }}</code></td>
-                    </tr>
-                    <tr>
-                      <td class="text-body-secondary">URL</td>
-                      <td><code class="text-break">{{ page.url }}</code></td>
-                    </tr>
-                    {% if page.date %}
-                    <tr>
-                      <td class="text-body-secondary">Date</td>
-                      <td><code>{{ page.date | date: "%Y-%m-%d" }}</code></td>
-                    </tr>
-                    {% endif %}
-                  </tbody>
-                </table>
-              </div>
-            </div>
+        </div>
+
+        <!-- Admin Quick Links -->
+        <div class="mb-3">
+          <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
+            <i class="bi bi-speedometer2 me-1"></i>Admin Dashboard
+          </h6>
+          <div class="list-group list-group-flush small">
+            <a href="{{ '/about/config/' | relative_url }}" class="list-group-item list-group-item-action d-flex align-items-center px-0">
+              <i class="bi bi-gear me-2 text-body-secondary"></i>Configuration
+            </a>
+            <a href="{{ '/about/settings/theme/' | relative_url }}" class="list-group-item list-group-item-action d-flex align-items-center px-0">
+              <i class="bi bi-palette me-2 text-body-secondary"></i>Theme Customizer
+            </a>
+            <a href="{{ '/about/settings/navigation/' | relative_url }}" class="list-group-item list-group-item-action d-flex align-items-center px-0">
+              <i class="bi bi-signpost-2 me-2 text-body-secondary"></i>Navigation Editor
+            </a>
           </div>
-          
         </div>
       </div>
       
-      <!-- Modal Footer -->
-      <div class="modal-footer">
-        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">
-          <i class="bi bi-x-lg me-1"></i>Close
-        </button>
+      <!-- Environment Tab -->
+      <div class="tab-pane fade" id="environment-pane" role="tabpanel" aria-labelledby="environment-tab" tabindex="0">
+        {% include components/env-switcher.html %}
+
+        <!-- Admin Link -->
+        <div class="mt-4 pt-3 border-top">
+          <a href="{{ '/about/settings/environment/' | relative_url }}" class="btn btn-outline-secondary btn-sm w-100">
+            <i class="bi bi-box-arrow-up-right me-1"></i>Full Environment &amp; Build Info
+          </a>
+        </div>
+      </div>
+      
+      <!-- Developer Tab -->
+      <div class="tab-pane fade" id="developer-pane" role="tabpanel" aria-labelledby="developer-tab" tabindex="0">
+        
+        <!-- Page Location -->
+        <div class="mb-4">
+          <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
+            <i class="bi bi-signpost-split me-1"></i>Page Location
+          </h6>
+          {% include navigation/breadcrumbs.html %}
+        </div>
+        
+        <!-- Source Code Shortcuts -->
+        <div class="mb-4">
+          <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
+            <i class="bi bi-code-square me-1"></i>Source Code
+          </h6>
+          {% include components/dev-shortcuts.html %}
+        </div>
+        
+        <!-- Page Metadata -->
+        <div class="mb-3">
+          <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
+            <i class="bi bi-file-earmark-code me-1"></i>Page Info
+          </h6>
+          <div class="table-responsive">
+            <table class="table table-sm table-hover mb-0 small">
+              <tbody>
+                <tr>
+                  <td class="text-body-secondary" style="width: 30%;">Layout</td>
+                  <td><code>{{ page.layout | default: "none" }}</code></td>
+                </tr>
+                <tr>
+                  <td class="text-body-secondary">Collection</td>
+                  <td><code>{{ page.collection | default: "none" }}</code></td>
+                </tr>
+                <tr>
+                  <td class="text-body-secondary">Path</td>
+                  <td><code class="text-break">{{ page.path }}</code></td>
+                </tr>
+                <tr>
+                  <td class="text-body-secondary">URL</td>
+                  <td><code class="text-break">{{ page.url }}</code></td>
+                </tr>
+                {% if page.date %}
+                <tr>
+                  <td class="text-body-secondary">Date</td>
+                  <td><code>{{ page.date | date: "%Y-%m-%d" }}</code></td>
+                </tr>
+                {% endif %}
+              </tbody>
+            </table>
+          </div>
+        </div>
       </div>
       
+      <!-- Background Tab -->
+      <div class="tab-pane fade" id="background-pane" role="tabpanel" aria-labelledby="background-tab" tabindex="0">
+        {% include components/background-settings.html %}
+      </div>
+
     </div>
   </div>
+  
 </div>

data/_includes/components/js-cdn.html

@@ -28,4 +28,7 @@
 <script type="module" src="{{ '/assets/js/modules/navigation/index.js' | relative_url }}"></script>
 
 <!-- Search modal controller -->
-<script src="{{ '/assets/js/search-modal.js' | relative_url }}"></script>
+<script src="{{ '/assets/js/search-modal.js' | relative_url }}"></script>
+
+<!-- fffuel-style background customizer (skin switching, toggle, opacity) -->
+<script src="{{ '/assets/js/background-customizer.js' | relative_url }}"></script>

data/_includes/components/nav-editor.html

@@ -0,0 +1,99 @@
+<!--
+  ===================================================================
+  NAV EDITOR — Read-only navigation tree view
+  ===================================================================
+
+  File: nav-editor.html
+  Path: _includes/components/nav-editor.html
+  Purpose: Renders all navigation data files as expandable card trees.
+           Each nav file becomes a card; items with children are nested.
+
+  Dependencies: Bootstrap 5 card/list-group, Bootstrap Icons,
+                _data/navigation/*.yml
+  Used by: pages/_about/settings/navigation.md
+  ===================================================================
+-->
+
+{% assign nav_files = "main,home,about,docs,posts,quickstart,admin" | split: "," %}
+
+<div class="row g-3 mb-3">
+  <div class="col-lg-4">
+    <div class="card text-center border-primary">
+      <div class="card-body py-3">
+        <i class="bi bi-signpost-2 fs-3 text-primary"></i>
+        <div class="fw-semibold mt-1">{{ nav_files | size }}</div>
+        <small class="text-body-secondary">Navigation Files</small>
+      </div>
+    </div>
+  </div>
+  <div class="col-lg-4">
+    <div class="card text-center border-primary">
+      <div class="card-body py-3">
+        <i class="bi bi-list-nested fs-3 text-primary"></i>
+        {% assign total_items = 0 %}
+        {% for nf in nav_files %}
+          {% assign items = site.data.navigation[nf] %}
+          {% if items %}{% assign total_items = total_items | plus: items.size %}{% endif %}
+        {% endfor %}
+        <div class="fw-semibold mt-1">{{ total_items }}</div>
+        <small class="text-body-secondary">Top-Level Items</small>
+      </div>
+    </div>
+  </div>
+  <div class="col-lg-4">
+    <div class="card text-center border-primary">
+      <div class="card-body py-3">
+        <i class="bi bi-folder2-open fs-3 text-primary"></i>
+        <div class="fw-semibold mt-1">_data/navigation/</div>
+        <small class="text-body-secondary">Source Directory</small>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div class="accordion" id="navAccordion">
+  {% for nf in nav_files %}
+    {% assign items = site.data.navigation[nf] %}
+    {% assign nf_id = nf | replace: '.', '-' %}
+    <div class="accordion-item">
+      <h2 class="accordion-header">
+        <button class="accordion-button {% unless forloop.first %}collapsed{% endunless %}" type="button"
+                data-bs-toggle="collapse" data-bs-target="#navAcc-{{ nf_id }}">
+          <i class="bi bi-file-earmark-text me-2"></i>
+          <strong>{{ nf }}.yml</strong>
+          {% if items %}
+            <span class="badge bg-secondary ms-2">{{ items | size }} items</span>
+          {% else %}
+            <span class="badge bg-warning ms-2">not found</span>
+          {% endif %}
+        </button>
+      </h2>
+      <div id="navAcc-{{ nf_id }}" class="accordion-collapse collapse {% if forloop.first %}show{% endif %}"
+           data-bs-parent="#navAccordion">
+        <div class="accordion-body p-0">
+          {% if items %}
+            <ul class="list-group list-group-flush">
+              {% for item in items %}
+                <li class="list-group-item">
+                  <div class="d-flex align-items-center">
+                    {% if item.icon %}<i class="{{ item.icon }} me-2 text-primary"></i>{% endif %}
+                    <div>
+                      <strong>{{ item.title }}</strong>
+                      {% if item.url %}<code class="ms-2 small">{{ item.url }}</code>{% endif %}
+                    </div>
+                    {% if item.external %}<span class="badge bg-info ms-auto">external</span>{% endif %}
+                  </div>
+                  {% if item.children %}
+                    <small class="text-body-secondary ms-4">{{ item.children | size }} sub-items</small>
+                  {% endif %}
+                </li>
+              {% endfor %}
+            </ul>
+          {% else %}
+            <div class="p-3 text-body-secondary small">No data file found for <code>{{ nf }}.yml</code></div>
+          {% endif %}
+        </div>
+      </div>
+    </div>
+  {% endfor %}
+</div>

data/_includes/components/setup-banner.html

@@ -0,0 +1,28 @@
+{% comment %}
+  ===================================================================
+  SETUP BANNER - Persistent notification for unconfigured sites
+  ===================================================================
+
+  File: setup-banner.html
+  Path: _includes/components/setup-banner.html
+  Purpose: Shows a dismissible top-bar when the site still needs
+           configuration. Disappears once site_configured is true.
+
+  Usage (add to root.html or any layout):
+    include components/setup-banner.html
+
+  Dependencies: components/setup-check.html (auto-included)
+  ===================================================================
+{% endcomment %}
+
+{% include components/setup-check.html %}
+
+{% if site_needs_setup %}
+<div class="alert alert-primary alert-dismissible fade show rounded-0 mb-0 py-2 text-center" role="alert" id="setup-banner">
+  <i class="bi bi-gear-wide-connected me-1"></i>
+  <strong>Almost there!</strong>
+  Your site is running with default settings.
+  <a href="{{ '/404.html' | relative_url }}" class="alert-link">Complete setup &rarr;</a>
+  <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
+</div>
+{% endif %}

data/_includes/components/setup-check.html

@@ -0,0 +1,53 @@
+{% comment %}
+  ===================================================================
+  SETUP CHECK - Detect unconfigured site state
+  ===================================================================
+
+  File: setup-check.html
+  Path: _includes/components/setup-check.html
+  Purpose: Provides Liquid variables to detect whether the site has been
+           configured by the user or is still running on theme defaults.
+
+  Usage:
+    {% include components/setup-check.html %}
+    {% if site_needs_setup %}
+      ... show setup guidance ...
+    {% endif %}
+
+  Detection Logic:
+    The include sets site_needs_setup to true when the site appears
+    to be running with default/unconfigured values. It checks:
+      1. Explicit site_configured: true flag (fastest path)
+      2. Whether the title is still the theme default
+      3. Whether founder/name are still theme defaults
+
+  Output Variables:
+    - site_needs_setup  : true if the site hasn't been personalised
+    - site_is_user_repo : true if this appears to be a <user>.github.io repo
+  ===================================================================
+{% endcomment %}
+
+{% comment %}
+  ── Determine if this is a user/org site (username.github.io) ──
+  User sites have an empty baseurl and a url ending in .github.io
+{% endcomment %}
+{% assign site_is_user_repo = false %}
+{% if site.baseurl == "" or site.baseurl == nil %}
+  {% if site.url contains ".github.io" %}
+    {% assign _url_path = site.url | split: "/" | last %}
+    {% unless _url_path contains "/" %}
+      {% assign site_is_user_repo = true %}
+    {% endunless %}
+  {% endif %}
+{% endif %}
+
+{% comment %}
+  ── Check if the site has been configured ──
+  Priority 1: Explicit flag in _config.yml
+  Priority 2: Heuristic — title/founder still match theme defaults
+{% endcomment %}
+{% assign site_needs_setup = false %}
+
+{% if site.site_configured == false %}
+  {% assign site_needs_setup = true %}
+{% endif %}