jekyll-theme-zer0 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61d06e485b7f208505ec171ac1d0f9b074124eb972085aaccb7a48957fe4a309
-  data.tar.gz: 8d725ba937bb2cac46d4f30d132380f6bdd24616f7e08f851bf0b8f3b3aa5383
+  metadata.gz: 492ac103c8adea1b4edaf2cf925f5a5e02d661e522907dec95cbf08ec0ab0ef6
+  data.tar.gz: 5efc803b2288fb9036165becc816e2b1f78cfa2e5aa62368049463e4eb7891c4
 SHA512:
-  metadata.gz: a4f72a346e3e8e1bad8affd72e8378d20669b5c937c187cbf1434c394a824ccdb2c303adf2cabd6734b24dac30216d294bb0047754d1c536c56e713ce5930287
-  data.tar.gz: b447257158432ebd4a5c6595af8cb842ac8b420b9624f66ebfc80e5cdc395c0b3074145051babd683675c78dcf00bd911ebb4e93522d19df6c9ab202ca1dcbe5
+  metadata.gz: 015f1f284b8129ae2788be7be74386818bdcd965b84d24aa4ba600fde13a91e4de2c211c068a28a69a959d30b18946b39cd4677fc21b1e8b2a44f59adf061edb
+  data.tar.gz: 06525dbbc0bea7d545293865e69b7c2f95352e213b3eee20db2a966f81f217d2ad88b02587f15f48b8e3d6f7a0adafb57978c5455638fd1a29fe79b980ca15ce

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.2.1] - 2026-04-22
+
+### Changed
+- Version bump: patch release
+
+### Commits in this release
+- 5c04e62 fix(footer,welcome,info): eliminate broken links on bare-minimum sites
+
+
+## [1.2.0] - 2026-04-22
+
+### Changed
+- Version bump: minor release
+
+### Commits in this release
+- 4bd3e36 feat(welcome): add bare-minimum 3-file remote-theme starter
+
+
 ## [1.1.0] - 2026-04-21
 
 ### Changed
@@ -12,7 +30,56 @@
 
 ## [Unreleased]
 
+### Added
+- **Bare-minimum 3-file remote-theme starter.** Consumers can now publish a
+  fully styled site to GitHub Pages with only `_config.yml`, `Gemfile`, and
+  `index.md` — no installer required. The new `_layouts/welcome.html` shipped
+  by the theme detects unconfigured sites and renders an onboarding screen
+  with a hero checklist, a 3-step starter accordion, and the embedded
+  `_includes/setup/wizard.html` that generates a personalised `_config.yml`
+  on the fly. README gained a "Bare-Minimum Starter" section documenting the
+  pattern.
+- **Smarter setup detection** in `_includes/components/setup-check.html`.
+  When `site_configured` is not set, the heuristic now flags a site as
+  unconfigured if it has no owner (`founder`/`author`/`email`) or its title
+  matches a known placeholder (`zer0-mistakes`, `zer0-pages-remote`,
+  `Your Site Title`, `My Awesome Site`, `Welcome`, `Untitled`, or empty).
+
 ### Fixed
+- **Footer Quick Links no longer 404 on bare-minimum sites.**
+  `_includes/core/footer.html` previously hard-coded links to
+  `/about/`, `/services/`, `/news/`, `/contact/`, `/privacy-policy`, and
+  `/terms-of-service` — none of which exist in a 3-file remote-theme
+  consumer. Quick Links are now resolved in this order:
+  1. `site.footer_quick_links` (array of `{label, url}`) — explicit override
+  2. Auto-detection: each candidate link only renders if the target page
+     exists in `site.html_pages`
+  3. Fallback to `Home` + `Sitemap (XML)` only.
+  Privacy Policy / Terms of Service links use the same existence check and
+  optionally read from `site.privacy_policy_url` / `site.terms_of_service_url`.
+- **Welcome layout external links now point to existing README anchors.**
+  The "Next steps" cards in `_layouts/welcome.html` linked to
+  `#content-creation` and `#customisation`, which don't exist in the theme
+  README. They now point to `README.md#-quick-start` and
+  `README.md#-key-features` respectively.
+- **Theme info admin links are conditional.**
+  `_includes/components/info-section.html` previously rendered Admin
+  Dashboard links to `/about/config/`, `/about/settings/theme/`,
+  `/about/settings/navigation/`, and `/about/settings/environment/`
+  unconditionally — guaranteed 404s on bare-minimum sites. The links and
+  surrounding section now only render when the corresponding page exists.
+- **Source Code shortcuts skip GitHub buttons when repository is unknown.**
+  `_includes/components/dev-shortcuts.html` rendered `https://github.com//blob//`
+  URLs when `site.repository` and `site.branch` were empty (typical on bare
+  consumer sites). It now hides the GitHub-based buttons and shows a hint
+  to set `repository: USER/REPO` in `_config.yml`.
+- **Cookie-consent privacy link is conditional.** The "Learn more in our
+  Privacy Policy" anchor in `_includes/components/cookie-consent.html` only
+  renders if a `/privacy-policy/` page exists or `site.privacy_policy_url` is
+  configured.
+- **Setup banner link.** `_includes/components/setup-banner.html` no longer
+  points at the non-existent `/404.html`; it now links to
+  `/#setup-wizard`, which is provided by the new welcome layout.
 - **Version-bump workflow no longer crashes on bash 5.x runners.** `scripts/utils/analyze-commits` (and `scripts/lib/changelog.sh`, `scripts/lib/migrate.sh`) used the `((var++))` post-increment idiom. On bash 5.x, when `var` is 0 the expression evaluates to 0 → exit code 1 → `set -euo pipefail` terminates the script silently. macOS bash 3.2 was more forgiving, so the bug only surfaced in CI. Replaced all release-path sites with `var=$((var + 1))`, which always returns 0. Added a static regression check to the unit tests so the pattern can't return.
 
 ## [1.0.0] - 2026-04-20

data/README.md

@@ -2,7 +2,7 @@
 title: zer0-mistakes
 sub-title: AI-Native Jekyll Theme
 description: AI-native Jekyll theme for GitHub Pages — Docker-first development, AI-powered installation, multi-agent integration (Copilot, Codex, Cursor, Claude), AI preview-image generation, and AIEO content optimization with Bootstrap 5.3.
-version: 1.1.0
+version: 1.2.1
 layout: landing
 tags:
   - jekyll
@@ -20,7 +20,7 @@ categories:
   - bootstrap
   - ai-tooling
 created: 2024-02-10T23:51:11.480Z
-lastmod: 2026-04-21T05:41:17.000Z
+lastmod: 2026-04-22T03:05:26.000Z
 draft: false
 permalink: /
 slug: zer0
@@ -158,25 +158,73 @@ docker-compose up
 # 🌐 Open http://localhost:4000
 ```
 
+### Bare-Minimum Starter (3 files, zero install)
+
+Don't want to run the installer? You can publish a working site to GitHub
+Pages with **just three files** in your repo. The remote theme provides every
+layout, style, and even an in-browser configuration wizard.
+
+```text
+my-site/
+├── _config.yml      ← site configuration (remote_theme: bamr87/zer0-mistakes)
+├── Gemfile          ← github-pages + jekyll-remote-theme
+└── index.md         ← layout: welcome
+```
+
+`_config.yml`:
+
+```yaml
+title:        "My Site"
+description:  "A site rendered by the zer0-mistakes remote theme."
+remote_theme: bamr87/zer0-mistakes
+plugins:
+  - jekyll-remote-theme
+  - jekyll-feed
+  - jekyll-sitemap
+  - jekyll-seo-tag
+site_configured: false   # show the welcome wizard until you flip this to true
+```
+
+`Gemfile`:
+
+```ruby
+source "https://rubygems.org"
+gem "github-pages", group: :jekyll_plugins
+gem "jekyll-remote-theme"
+gem "webrick", "~> 1.7"
+```
+
+`index.md`:
+
+```markdown
+---
+layout: welcome
+title: Home
+---
+
+# Welcome to my site
+```
+
+Push to a GitHub Pages–enabled repository and visit your site. Until you set
+`site_configured: true`, the home page renders the **welcome layout** —
+a hero card listing your three files, a 3-step starter accordion, and a full
+in-browser wizard that generates a personalised `_config.yml` you can
+download. Once you flip the flag (or fill in `title`/`founder`/`email`), the
+welcome screen is replaced by your own content.
+
 ```mermaid
 sequenceDiagram
     participant You
-    participant InstallScript as Install Script
-    participant Docker
-    participant Browser
-
-    You->>InstallScript: curl ... | bash
-    InstallScript->>InstallScript: Detect platform
-    InstallScript->>InstallScript: Download theme files
-    InstallScript->>InstallScript: Configure Docker
-    InstallScript-->>You: ✅ Ready
-
-    You->>Docker: docker-compose up
-    Docker->>Docker: Build Jekyll container
-    Docker->>Docker: Install dependencies
-    Docker-->>Browser: Serve on :4000
-
-    Browser-->>You: 🎉 Live site
+    participant GitHubPages as GitHub Pages
+    participant RemoteTheme as bamr87/zer0-mistakes
+
+    You->>GitHubPages: push 3 files
+    GitHubPages->>RemoteTheme: fetch layouts/includes/assets
+    RemoteTheme-->>GitHubPages: welcome.html + setup wizard
+    GitHubPages-->>You: 🎉 onboarding screen at /
+    You->>You: use wizard to generate _config.yml
+    You->>GitHubPages: replace _config.yml + set site_configured: true
+    GitHubPages-->>You: 🚀 your customised site
 ```
 
 ---
@@ -1066,7 +1114,7 @@ git push origin feature/awesome-feature
 
 | Metric | Value |
 |--------|-------|
-| **Current Version** | 1.1.0 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
+| **Current Version** | 1.2.1 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
 | **Documented Features** | 43 ([Feature Registry](https://github.com/bamr87/zer0-mistakes/blob/main/_data/features.yml)) |
 | **Setup Time** | 2-5 minutes ([install.sh benchmarks](https://github.com/bamr87/zer0-mistakes/blob/main/install.sh)) |
 | **Documentation Pages** | 70+ ([browse docs](/pages/)) |
@@ -1117,6 +1165,6 @@ And these AI partners that make zer0-mistakes truly AI-native:
 
 **Built with ❤️ — and a little help from our AI partners — for the Jekyll community**
 
-**v1.1.0** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
+**v1.2.1** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
 
 

data/_includes/components/cookie-consent.html

@@ -59,7 +59,11 @@ Configuration: Uses site.posthog settings from _config.yml
         </p>
         <p class="mb-2 mb-lg-0 small text-white-50">
           This website uses cookies and similar technologies to enhance your browsing experience, analyze traffic, and provide personalized content.
-          <a href="{{ '/privacy-policy/' | relative_url }}" class="text-white text-decoration-underline">Learn more in our Privacy Policy</a>.
+          {% assign _pp = site.html_pages | where: "url", "/privacy-policy/" | first %}
+          {% unless _pp %}{% assign _pp = site.html_pages | where: "url", "/privacy-policy" | first %}{% endunless %}
+          {% if _pp or site.privacy_policy_url %}
+            <a href="{{ site.privacy_policy_url | default: '/privacy-policy/' | relative_url }}" class="text-white text-decoration-underline">Learn more in our Privacy Policy</a>.
+          {% endif %}
         </p>
       </div>
       <div class="col-12 col-lg-4">

data/_includes/components/dev-shortcuts.html

@@ -33,6 +33,11 @@
 <div class="dev-shortcuts">
   <div class="d-flex flex-column gap-2">
 
+    {% comment %} Skip all GitHub-based shortcuts on bare/unconfigured sites where
+       site.repository or site.branch are empty (otherwise we render
+       https://github.com//blob//path → 404). {% endcomment %}
+    {% if site.repository and site.branch %}
+
     <!-- Button Group (section title is the parent h6 in info-section.html) -->
     <div class="btn-group-vertical" role="group" aria-label="Source code shortcuts">
 
@@ -109,5 +114,13 @@
 
     </div>
 
+    {% else %}
+      <p class="small text-body-secondary mb-0">
+        <i class="bi bi-info-circle me-1"></i>
+        Set <code>repository: USER/REPO</code> in your <code>_config.yml</code>
+        to enable source-code shortcuts.
+      </p>
+    {% endif %}
+
   </div>
 </div>

data/_includes/components/info-section.html

@@ -108,35 +108,51 @@
           </div>
         </div>
 
-        <!-- Admin Quick Links -->
+        <!-- Admin Quick Links — only render links to pages that actually exist
+             in the build (prevents 404s on bare-minimum / remote-theme sites
+             that haven't created the admin pages). -->
+        {% assign _cfg_page = site.html_pages | where: "url", "/about/config/" | first %}
+        {% assign _theme_page = site.html_pages | where: "url", "/about/settings/theme/" | first %}
+        {% assign _nav_page = site.html_pages | where: "url", "/about/settings/navigation/" | first %}
+        {% if _cfg_page or _theme_page or _nav_page %}
         <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">
+            {% if _cfg_page %}
             <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>
+            {% endif %}
+            {% if _theme_page %}
             <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>
+            {% endif %}
+            {% if _nav_page %}
             <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>
+            {% endif %}
           </div>
         </div>
+        {% endif %}
       </div>
       
       <!-- 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 -->
+        <!-- Admin Link — only when target page exists -->
+        {% assign _env_page = site.html_pages | where: "url", "/about/settings/environment/" | first %}
+        {% if _env_page %}
         <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>
+        {% endif %}
       </div>
       
       <!-- Developer Tab -->

data/_includes/components/setup-banner.html

@@ -22,7 +22,7 @@
   <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>
+  <a href="{{ '/' | relative_url }}#setup-wizard" 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

@@ -48,6 +48,37 @@
 {% endcomment %}
 {% assign site_needs_setup = false %}
 
+{% comment %} Explicit opt-out (configured sites set this to true). {% endcomment %}
 {% if site.site_configured == false %}
   {% assign site_needs_setup = true %}
 {% endif %}
+
+{% comment %}
+  ── Heuristic detection (when site_configured is not set explicitly) ──
+  Treat the site as "needs setup" if any of these are true:
+    • No founder/author/email configured
+    • Title is empty or matches a known placeholder
+    • The site has no content collections beyond the defaults
+{% endcomment %}
+{% unless site.site_configured %}
+  {% assign _has_owner = false %}
+  {% if site.founder or site.author or site.email %}
+    {% assign _has_owner = true %}
+  {% endif %}
+
+  {% assign _placeholder_titles = "zer0-mistakes,zer0-pages-remote,Your Site Title,My Awesome Site,Welcome,Untitled" | split: "," %}
+  {% assign _title_is_placeholder = false %}
+  {% if site.title == nil or site.title == "" %}
+    {% assign _title_is_placeholder = true %}
+  {% else %}
+    {% for _t in _placeholder_titles %}
+      {% if site.title == _t %}
+        {% assign _title_is_placeholder = true %}
+      {% endif %}
+    {% endfor %}
+  {% endif %}
+
+  {% if _has_owner == false or _title_is_placeholder %}
+    {% assign site_needs_setup = true %}
+  {% endif %}
+{% endunless %}

data/_includes/core/footer.html

@@ -80,16 +80,33 @@
             {% if site.email %}<p class="mb-0"><a href="mailto:{{ site.email }}" class="text-light text-decoration-none">{{ site.email }}</a></p>{% endif %}
           </div>
 
-          <!-- Quick Links -->
+          <!-- Quick Links
+               Resolution order:
+                 1. site.footer_quick_links  (array of {label, url}) — explicit override
+                 2. Auto-detection: only render links whose target pages
+                    actually exist in the build. Prevents 404s on bare-minimum
+                    sites that haven't created /about/, /services/, etc. -->
           <div class="col-12 col-md-6 col-lg-3 mb-3">
             <h5 class="text-uppercase mb-3">Quick Links</h5>
             <ul class="list-unstyled" aria-label="Footer quick links">
-              <li><a href="{{ '/' | relative_url }}" class="text-light text-decoration-none">Home</a></li>
-              <li><a href="{{ '/about/' | relative_url }}" class="text-light text-decoration-none">About</a></li>
-              <li><a href="{{ '/services/' | relative_url }}" class="text-light text-decoration-none">Services</a></li>
-              <li><a href="{{ '/news/' | relative_url }}" class="text-light text-decoration-none">News</a></li>
-              <li><a href="{{ '/contact/' | relative_url }}" class="text-light text-decoration-none">Contact</a></li>
-              <li><a href="{{ '/sitemap.xml' | relative_url }}" class="text-light text-decoration-none">Sitemap (XML)</a></li>
+              {% if site.footer_quick_links %}
+                {% for link in site.footer_quick_links %}
+                  <li><a href="{{ link.url | relative_url }}" class="text-light text-decoration-none">{{ link.label }}</a></li>
+                {% endfor %}
+              {% else %}
+                <li><a href="{{ '/' | relative_url }}" class="text-light text-decoration-none">Home</a></li>
+                {% assign _candidate_links = "About,/about/|Services,/services/|News,/news/|Contact,/contact/" | split: "|" %}
+                {% for entry in _candidate_links %}
+                  {% assign _parts = entry | split: "," %}
+                  {% assign _label = _parts[0] %}
+                  {% assign _url   = _parts[1] %}
+                  {% assign _page  = site.html_pages | where: "url", _url | first %}
+                  {% if _page %}
+                    <li><a href="{{ _url | relative_url }}" class="text-light text-decoration-none">{{ _label }}</a></li>
+                  {% endif %}
+                {% endfor %}
+                <li><a href="{{ '/sitemap.xml' | relative_url }}" class="text-light text-decoration-none">Sitemap (XML)</a></li>
+              {% endif %}
             </ul>
           </div>
 
@@ -151,8 +168,17 @@
           </div>
           <div class="col-md-4 text-md-end">
             <ul class="list-inline mb-0">
-              <li class="list-inline-item"><a href="{{ '/privacy-policy' | relative_url }}" class="text-light text-decoration-none">Privacy Policy</a></li>
-              <li class="list-inline-item"><a href="{{ '/terms-of-service' | relative_url }}" class="text-light text-decoration-none">Terms of Service</a></li>
+              {% comment %} Only render policy links whose pages exist (or that are explicitly configured). {% endcomment %}
+              {% assign _privacy = site.html_pages | where: "url", "/privacy-policy/" | first %}
+              {% unless _privacy %}{% assign _privacy = site.html_pages | where: "url", "/privacy-policy" | first %}{% endunless %}
+              {% if _privacy or site.privacy_policy_url %}
+                <li class="list-inline-item"><a href="{{ site.privacy_policy_url | default: '/privacy-policy' | relative_url }}" class="text-light text-decoration-none">Privacy Policy</a></li>
+              {% endif %}
+              {% assign _terms = site.html_pages | where: "url", "/terms-of-service/" | first %}
+              {% unless _terms %}{% assign _terms = site.html_pages | where: "url", "/terms-of-service" | first %}{% endunless %}
+              {% if _terms or site.terms_of_service_url %}
+                <li class="list-inline-item"><a href="{{ site.terms_of_service_url | default: '/terms-of-service' | relative_url }}" class="text-light text-decoration-none">Terms of Service</a></li>
+              {% endif %}
               <li class="list-inline-item">
                 <a href="#" class="text-light text-decoration-none" data-bs-toggle="modal" data-bs-target="#cookieSettingsModal">
                   Cookie Preferences

data/_layouts/welcome.html

@@ -0,0 +1,337 @@
+---
+layout: root
+---
+<!--
+  ===================================================================
+  WELCOME LAYOUT — Onboarding landing page for new sites
+  ===================================================================
+
+  File: welcome.html
+  Path: _layouts/welcome.html
+  Inherits: root.html
+  Purpose: First-run experience for sites that have just installed the
+           bamr87/zer0-mistakes remote theme but haven't configured
+           anything yet. Shows the configuration wizard, the minimal
+           starter checklist, and links to docs.
+
+  Behaviour:
+    • If the site is unconfigured (see components/setup-check.html),
+      the wizard + instructions REPLACE the page content.
+    • Once site.site_configured == true (or the heuristic passes),
+      the page renders the user's content normally.
+
+  Recommended usage in a brand-new repo:
+
+      # index.md (one of the only three files you need)
+      ---
+      layout: welcome
+      title: Home
+      ---
+
+      Welcome to my new site!  ← shown after configuration is complete
+
+  Companion files in a minimal starter:
+      _config.yml   (just `remote_theme: bamr87/zer0-mistakes`)
+      Gemfile       (github-pages + jekyll-remote-theme)
+      index.md      (this layout)
+  ===================================================================
+-->
+
+{% include components/setup-check.html %}
+
+{% if site_needs_setup %}
+
+  <!-- ============================================================ -->
+  <!-- HERO                                                          -->
+  <!-- ============================================================ -->
+  <section class="bg-body-tertiary border-bottom">
+    <div class="container-lg py-5">
+      <div class="row align-items-center g-4">
+        <div class="col-lg-7">
+          <span class="badge text-bg-primary mb-2">
+            <i class="bi bi-stars"></i> zer0-mistakes remote theme
+          </span>
+          <h1 class="display-5 fw-bold mb-3">
+            Welcome — your site is live!
+          </h1>
+          <p class="lead mb-3">
+            GitHub Pages built this page from <strong>just three files</strong>
+            in your repository. The layout, styles, and this entire onboarding
+            screen are served by the remote theme.
+          </p>
+          <p class="text-body-secondary mb-4">
+            Use the wizard below to generate a personalised
+            <code>_config.yml</code>, drop it into your repo, and your site
+            will look like <em>your</em> site instead of this welcome page.
+          </p>
+          <div class="d-flex flex-wrap gap-2">
+            <a href="#setup-wizard" class="btn btn-primary btn-lg">
+              <i class="bi bi-magic"></i> Start the wizard
+            </a>
+            <a href="#minimal-starter" class="btn btn-outline-secondary btn-lg">
+              <i class="bi bi-list-check"></i> Minimal starter
+            </a>
+          </div>
+        </div>
+        <div class="col-lg-5">
+          <div class="card shadow-sm">
+            <div class="card-header bg-body">
+              <i class="bi bi-folder2-open"></i>
+              <strong>Your repository right now</strong>
+            </div>
+            <div class="card-body p-0">
+              <ul class="list-group list-group-flush small mb-0">
+                <li class="list-group-item d-flex justify-content-between align-items-center">
+                  <span><i class="bi bi-file-earmark-text"></i> <code>_config.yml</code></span>
+                  <span class="badge text-bg-success rounded-pill">required</span>
+                </li>
+                <li class="list-group-item d-flex justify-content-between align-items-center">
+                  <span><i class="bi bi-gem"></i> <code>Gemfile</code></span>
+                  <span class="badge text-bg-success rounded-pill">required</span>
+                </li>
+                <li class="list-group-item d-flex justify-content-between align-items-center">
+                  <span><i class="bi bi-house-door"></i> <code>index.md</code></span>
+                  <span class="badge text-bg-success rounded-pill">required</span>
+                </li>
+                <li class="list-group-item d-flex justify-content-between align-items-center text-body-secondary">
+                  <span><i class="bi bi-folder"></i> <code>pages/</code></span>
+                  <span class="badge text-bg-secondary rounded-pill">optional</span>
+                </li>
+                <li class="list-group-item d-flex justify-content-between align-items-center text-body-secondary">
+                  <span><i class="bi bi-folder"></i> <code>assets/</code></span>
+                  <span class="badge text-bg-secondary rounded-pill">optional</span>
+                </li>
+              </ul>
+            </div>
+            <div class="card-footer text-body-secondary small">
+              Everything else — layouts, styles, navigation, search —
+              is provided by the remote theme.
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <!-- ============================================================ -->
+  <!-- MINIMAL STARTER INSTRUCTIONS                                  -->
+  <!-- ============================================================ -->
+  <section id="minimal-starter" class="container-lg py-5">
+    <div class="row justify-content-center">
+      <div class="col-lg-10">
+        <h2 class="mb-3"><i class="bi bi-list-check"></i> The 3-file starter</h2>
+        <p class="text-body-secondary">
+          The only files you need in your repository for GitHub Pages to
+          render a full site through the <code>bamr87/zer0-mistakes</code>
+          remote theme.
+        </p>
+
+        <div class="accordion mt-4" id="starterAccordion">
+
+          <!-- _config.yml -->
+          <div class="accordion-item">
+            <h3 class="accordion-header">
+              <button class="accordion-button" type="button"
+                      data-bs-toggle="collapse" data-bs-target="#starter-config">
+                <i class="bi bi-1-circle me-2"></i>
+                <code>_config.yml</code>
+                <span class="text-body-secondary ms-2">— site configuration</span>
+              </button>
+            </h3>
+            <div id="starter-config" class="accordion-collapse collapse show"
+                 data-bs-parent="#starterAccordion">
+              <div class="accordion-body">
+                <p>The minimum viable configuration:</p>
+{% highlight yaml %}
+# _config.yml
+title:        "My Site"
+description:  "A site rendered by the zer0-mistakes remote theme."
+url:          ""
+baseurl:      ""
+
+# Pull layouts/includes/assets from the published theme
+remote_theme: bamr87/zer0-mistakes
+
+# GitHub Pages whitelisted plugins
+plugins:
+  - jekyll-remote-theme
+  - jekyll-feed
+  - jekyll-sitemap
+  - jekyll-seo-tag
+
+# Hide this welcome screen once you're configured
+site_configured: true
+{% endhighlight %}
+                <p class="small text-body-secondary mb-0">
+                  Use the wizard below to generate a richer file with
+                  collections, analytics, and social links.
+                </p>
+              </div>
+            </div>
+          </div>
+
+          <!-- Gemfile -->
+          <div class="accordion-item">
+            <h3 class="accordion-header">
+              <button class="accordion-button collapsed" type="button"
+                      data-bs-toggle="collapse" data-bs-target="#starter-gemfile">
+                <i class="bi bi-2-circle me-2"></i>
+                <code>Gemfile</code>
+                <span class="text-body-secondary ms-2">— Ruby dependencies</span>
+              </button>
+            </h3>
+            <div id="starter-gemfile" class="accordion-collapse collapse"
+                 data-bs-parent="#starterAccordion">
+              <div class="accordion-body">
+                <p>Required when building locally; GitHub Pages installs these for you in CI.</p>
+{% highlight ruby %}
+# Gemfile
+source "https://rubygems.org"
+
+gem "github-pages", group: :jekyll_plugins
+gem "jekyll-remote-theme"
+gem "webrick", "~> 1.7"
+{% endhighlight %}
+              </div>
+            </div>
+          </div>
+
+          <!-- index.md -->
+          <div class="accordion-item">
+            <h3 class="accordion-header">
+              <button class="accordion-button collapsed" type="button"
+                      data-bs-toggle="collapse" data-bs-target="#starter-index">
+                <i class="bi bi-3-circle me-2"></i>
+                <code>index.md</code>
+                <span class="text-body-secondary ms-2">— your home page</span>
+              </button>
+            </h3>
+            <div id="starter-index" class="accordion-collapse collapse"
+                 data-bs-parent="#starterAccordion">
+              <div class="accordion-body">
+                <p>
+                  While the site is unconfigured, <code>layout: welcome</code>
+                  shows this onboarding screen. Once you set
+                  <code>site_configured: true</code> in <code>_config.yml</code>,
+                  the same file renders your own home-page content.
+                </p>
+{% highlight markdown %}
+---
+layout: welcome
+title: Home
+---
+
+# Welcome to my site
+
+Replace this with your own content. The setup wizard
+will disappear automatically once `site_configured: true`
+is set in `_config.yml`.
+{% endhighlight %}
+              </div>
+            </div>
+          </div>
+
+        </div><!-- /accordion -->
+
+        <div class="alert alert-info d-flex align-items-start mt-4" role="alert">
+          <i class="bi bi-info-circle-fill me-2 mt-1"></i>
+          <div>
+            <strong>Local development?</strong>
+            Run <code>bundle install &amp;&amp; bundle exec jekyll serve</code>
+            (or <code>docker compose up</code> if you have a
+            <code>docker-compose.yml</code>). Browse to
+            <a href="http://localhost:4000/">http://localhost:4000/</a>.
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <!-- ============================================================ -->
+  <!-- SETUP WIZARD                                                  -->
+  <!-- ============================================================ -->
+  <section id="setup-wizard" class="bg-body-tertiary border-top py-5">
+    {% include setup/wizard.html %}
+  </section>
+
+  <!-- ============================================================ -->
+  <!-- NEXT STEPS / RESOURCES                                        -->
+  <!-- ============================================================ -->
+  <section class="container-lg py-5">
+    <h2 class="mb-4"><i class="bi bi-signpost-2"></i> Next steps</h2>
+    <div class="row g-3">
+      <div class="col-md-4">
+        <div class="card h-100">
+          <div class="card-body">
+            <h5 class="card-title">
+              <i class="bi bi-pencil-square text-primary"></i> Add content
+            </h5>
+            <p class="card-text small">
+              Create a <code>pages/</code> folder with collections like
+              <code>_posts/</code>, <code>_docs/</code>, or
+              <code>_about/</code>. Enable them in <code>_config.yml</code>.
+            </p>
+            <a class="btn btn-sm btn-outline-primary"
+               href="https://github.com/bamr87/zer0-mistakes/blob/main/README.md#-quick-start"
+               target="_blank" rel="noopener">
+              Content guide <i class="bi bi-box-arrow-up-right"></i>
+            </a>
+          </div>
+        </div>
+      </div>
+      <div class="col-md-4">
+        <div class="card h-100">
+          <div class="card-body">
+            <h5 class="card-title">
+              <i class="bi bi-palette text-success"></i> Customise styles
+            </h5>
+            <p class="card-text small">
+              Drop an <code>assets/css/user-overrides.css</code> file in
+              your repo to override theme styles without forking.
+            </p>
+            <a class="btn btn-sm btn-outline-success"
+               href="https://github.com/bamr87/zer0-mistakes/blob/main/README.md#-key-features"
+               target="_blank" rel="noopener">
+              Customisation <i class="bi bi-box-arrow-up-right"></i>
+            </a>
+          </div>
+        </div>
+      </div>
+      <div class="col-md-4">
+        <div class="card h-100">
+          <div class="card-body">
+            <h5 class="card-title">
+              <i class="bi bi-github text-body"></i> Source &amp; issues
+            </h5>
+            <p class="card-text small">
+              File issues, submit PRs, or fork the theme on GitHub.
+              Contributions welcome.
+            </p>
+            <a class="btn btn-sm btn-outline-dark"
+               href="https://github.com/bamr87/zer0-mistakes"
+               target="_blank" rel="noopener">
+              Repository <i class="bi bi-box-arrow-up-right"></i>
+            </a>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+
+{% else %}
+
+  <!-- ============================================================ -->
+  <!-- CONFIGURED SITE — render the user's content                   -->
+  <!-- ============================================================ -->
+  <div class="container-lg py-4">
+    <div class="row justify-content-center">
+      <div class="col-lg-10">
+        {% if page.title %}
+          <h1 class="mb-3">{{ page.title }}</h1>
+        {% endif %}
+        {{ content }}
+      </div>
+    </div>
+  </div>
+
+{% endif %}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-zer0
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Amr Abdel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-21 00:00:00.000000000 Z
+date: 2026-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -193,6 +193,7 @@ files:
 - _layouts/sitemap-collection.html
 - _layouts/stats.html
 - _layouts/tag.html
+- _layouts/welcome.html
 - _plugins/preview_image_generator.rb
 - _plugins/theme_version.rb
 - _sass/core/_docs-layout.scss