jekyll-theme-zer0 0.1.8 → 0.2.1

data/_layouts/default.html

@@ -1,37 +1,85 @@
 ---
 layout: root
 ---
-<!-- _
-  file: default.html
-  path: _layouts/default.html
-  includes: sidebar-left.html, sidebar-right.html
+<!--
+  ===================================================================
+  DEFAULT LAYOUT - Standard content layout with sidebars
+  ===================================================================
+  
+  File: default.html
+  Path: _layouts/default.html
+  Inherits: root.html
+  Purpose: Primary content layout with sidebar navigation and table of contents
+  
+  Template Logic:
+  - Creates a responsive three-column layout using Bootstrap grid
+  - Left sidebar: Site navigation and content outline (collapsible on mobile)
+  - Center: Main content area with page title and body content
+  - Right sidebar: Table of contents and page shortcuts (hidden on mobile)
+  - Implements scroll spy for navigation highlighting
+  - Responsive design that stacks vertically on mobile devices
+  
+  Layout Structure:
+  1. Container wrapper with Bootstrap responsive classes
+  2. Left sidebar (bd-sidebar) - Navigation and outline
+  3. Main content area (bd-main) with:
+     - Intro section (page title, metadata)
+     - Right sidebar (bd-toc) - Table of contents
+     - Content area (bd-content) - Main page content
+  
+  Dependencies:
+  - sidebar-left.html: Site navigation and content outline
+  - intro.html: Page title, breadcrumbs, and metadata
+  - sidebar-right.html: Table of contents and page shortcuts
+  
+  Bootstrap Classes Used:
+  - container-xxl: Extra large responsive container
+  - bd-gutter: Custom Bootstrap spacing
+  - bd-layout: Custom layout utility class
+  - bd-sidebar: Custom sidebar styling
+  - bd-main: Main content area
+  - bd-toc: Table of contents styling
+  - bd-content: Content area styling
+  ===================================================================
 -->
 
-<!-- Default Layout - Docs -->
-
-<!-- Main body including sidebars -->
+<!-- ================================================ -->
+<!-- MAIN LAYOUT CONTAINER                           -->
+<!-- Bootstrap responsive container with custom grid -->
+<!-- ================================================ -->
 <div class="container-xxl bd-gutter mt-3 my-md-4 bd-layout">
 
-  <!-- Left Sidebar for Outline - Offcanvas -->
-  <!-- _includes/sidebar-left.html  -->
-  <aside class=" bd-sidebar ">
-    {% include sidebar-left.html %}
-  </aside>
+    <!-- ================================ -->
+    <!-- LEFT SIDEBAR - Navigation       -->
+    <!-- ================================ -->
+    <!-- Site navigation, content outline, and offcanvas menu for mobile -->
+    <aside class="bd-sidebar">
+        {% include navigation/sidebar-left.html %}
+    </aside>
     
-    <!--  Main Body -->
-  <main class="bd-main order-1" data-spy="scroll" data-bs-target="toc-content" data-offset="0">
+    <!-- ================================ -->
+    <!-- MAIN CONTENT AREA               -->
+    <!-- ================================ -->
+    <!-- Primary content section with scroll spy for table of contents navigation -->
+    <main class="bd-main order-1" data-spy="scroll" data-bs-target="toc-content" data-offset="0">
 
-      <!-- intro -->
-    {% include intro.html %}
+        <!-- Page introduction: title, breadcrumbs, metadata -->
+        {% include content/intro.html %}
 
-    <!-- Right Sidebar - Page Contents and Shortcuts-->
-    <!-- _includes/sidebar-right.html  -->
-    <div class="bd-toc text-body-secondary" >
-      {% include sidebar-right.html %}
-    </div>
-    <!-- Main Content -->
-    <div id="main-content" class="bd-content ps-lg-2">
-      {{ content }}
-    </div>
-  </main>
+        <!-- =============================== -->
+        <!-- RIGHT SIDEBAR - Table of Contents -->
+        <!-- =============================== -->
+        <!-- Page outline, shortcuts, and related links (hidden on mobile) -->
+        <div class="bd-toc text-body-secondary">
+            {% include navigation/sidebar-right.html %}
+        </div>
+        
+        <!-- =============================== -->
+        <!-- MAIN CONTENT BODY              -->
+        <!-- =============================== -->
+        <!-- Where the actual page content is rendered -->
+        <div id="main-content" class="bd-content ps-lg-2">
+            {{ content }}
+        </div>
+    </main>
 </div>

data/_layouts/home.html

@@ -1,16 +1,66 @@
 ---
 layout: root
 ---
-
-<!-- Home Layout -->
-
-<div class="home">
-  {%- if page.title -%}
-    <h1 class="page-heading">{{ page.title }}</h1>
-  {%- endif -%}
+<!--
+  ===================================================================
+  HOME LAYOUT - Homepage template with minimal structure
+  ===================================================================
+  
+  File: home.html
+  Path: _layouts/home.html
+  Inherits: root.html
+  Purpose: Clean, minimal layout for the site homepage
   
-  {{ content }}
+  Template Logic:
+  - Provides a simple container for homepage content
+  - Conditionally displays page title if specified in frontmatter
+  - Includes RSS feed subscription link for blog functionality
+  - Bypasses the sidebar navigation system for a cleaner look
+  - Focuses on content presentation without distractions
+  
+  Layout Structure:
+  1. Main home container wrapper
+  2. Optional page title (controlled by frontmatter)
+  3. Main content area (from Markdown or HTML)
+  4. RSS subscription link for blog updates
+  
+  Usage:
+  - Set layout: home in page frontmatter
+  - Optionally include title: "Page Title" for display
+  - Content can include hero sections, feature highlights, etc.
+  
+  Design Philosophy:
+  - Minimal structure allows for maximum content flexibility
+  - RSS link maintains blog connectivity
+  - Clean presentation suitable for landing pages
+  ===================================================================
+-->
 
-    <p class="rss-subscribe">subscribe <a href="{{ "/feed.xml" | relative_url }}">via RSS</a></p>
+<!-- ================================ -->
+<!-- HOME PAGE CONTAINER             -->
+<!-- ================================ -->
+<div class="home">
+    <!-- ========================== -->
+    <!-- OPTIONAL PAGE TITLE        -->
+    <!-- ========================== -->
+    <!-- Display title only if specified in page frontmatter -->
+    <!-- Usage: Add 'title: "Homepage Title"' to page frontmatter -->
+    {%- if page.title -%}
+        <h1 class="page-heading">{{ page.title }}</h1>
+    {%- endif -%}
+    
+    <!-- ========================== -->
+    <!-- MAIN CONTENT AREA          -->
+    <!-- ========================== -->
+    <!-- Homepage content rendered from Markdown or HTML -->
+    <!-- Can include hero sections, feature cards, etc. -->
+    {{ content }}
 
+    <!-- ========================== -->
+    <!-- RSS SUBSCRIPTION LINK      -->
+    <!-- ========================== -->
+    <!-- Provides easy access to RSS feed for blog updates -->
+    <p class="rss-subscribe">
+        subscribe <a href="{{ "/feed.xml" | relative_url }}">via RSS</a>
+    </p>
 </div>

data/_layouts/index.html

@@ -1,8 +1,54 @@
 ---
 layout: root
 ---
-<!-- Site Indexing template for search functionality -->
+<!--
+  ===================================================================
+  INDEX LAYOUT - Search indexing template
+  ===================================================================
+  
+  File: index.html
+  Path: _layouts/index.html
+  Inherits: root.html
+  Purpose: Specialized layout for search functionality and site indexing
+  
+  Template Logic:
+  - Provides a clean container for search-related content
+  - Uses fluid container for full-width search interfaces
+  - Implements proper spacing with Bootstrap padding classes
+  - Bypasses sidebar navigation for focused search experience
+  
+  Layout Features:
+  - Full-width fluid container for search components
+  - Responsive padding that adapts to screen size
+  - Clean, minimal structure to highlight search functionality
+  - Semantic HTML5 structure with proper search context
+  
+  Usage:
+  - Typically used for search result pages
+  - Site indexing and content discovery pages
+  - Archive pages with search functionality
+  - Any page requiring full-width content presentation
+  
+  Search Integration:
+  - Can be integrated with Algolia, Lunr.js, or other search engines
+  - Provides container for search forms, filters, and results
+  - Supports dynamic content loading and filtering
+  
+  Accessibility:
+  - Uses semantic search-index ID for screen readers
+  - Provides proper container context for search tools
+  - Maintains consistent navigation patterns
+  ===================================================================
+-->
 
+<!-- ================================ -->
+<!-- SEARCH INDEX CONTAINER          -->
+<!-- ================================ -->
+<!-- Full-width container optimized for search interfaces and content discovery -->
 <div id="search-index" class="container-fluid pt-5 py-5">
+    <!-- ========================== -->
+    <!-- SEARCH CONTENT AREA        -->
+    <!-- ========================== -->
+    <!-- Main content area for search forms, results, filters, and indexing -->
     {{ content }}
 </div>

data/_layouts/journals.html

@@ -1,41 +1,33 @@
 ---
 layout: default
 ---
-
-<!-- Journals Layout -->
+<!--
+  Simple journals layout for debugging stack overflow issue
+-->
 
 <div id="main" role="main">
     <div class="archive">
-        {% unless page.header.overlay_color or page.header.overlay_image %}
-        <h1 id="page-title" class="">{{ page.title }}</h1>
-        {% endunless %}
+        <h1 id="page-title">{{ page.title }}</h1>
         {{ content }}
     </div>
-
+    
+    <!-- Simple navigation without complex logic -->
     <nav aria-label="Page navigation">
         <ul class="pagination pagination-lg justify-content-center">
             <li class="page-item">
                 {% if page.previous %}
-                    <a class="page-link" href="{{ page.previous.url | prepend: site.baseurl }}">
-                        Previous: {{ page.previous.title }}
-                    </a>
+                    <a class="page-link" href="{{ page.previous.url }}">Previous</a>
                 {% else %}
-                    <a class="page-link" href="#" aria-disabled="true">Previous</a>
+                    <span class="page-link disabled">Previous</span>
                 {% endif %}
             </li>
             <li class="page-item">
                 {% if page.next %}
-                    <a class="page-link" href="{{ page.next.url | prepend: site.baseurl }}">
-                        Next: {{ page.next.title }}
-                    </a>
+                    <a class="page-link" href="{{ page.next.url }}">Next</a>
                 {% else %}
-                    <a class="page-link" href="#" aria-disabled="true">Next</a>
+                    <span class="page-link disabled">Next</span>
                 {% endif %}
             </li>
         </ul>
     </nav>
-</div>
-
-{% if page.comments %}
-    {% include giscus.html %}
-{% endif %}
+</div>

data/_layouts/landing.html

@@ -1,18 +1,154 @@
 ---
 layout: root
 ---
-
-  <!-- Left Sidebar for Outline - Offcanvas -->
-  <!-- _includes/sidebar-left.html  -->
-  <div class="offcanvas">
-    {% include sidebar-left.html %}
-  </div>
-  <div class="container-xl pt-5">
+<!--
+  ===================================================================
+  LANDING LAYOUT - Welcome page for first-time visitors
+  ===================================================================
+  
+  File: landing.html
+  Path: _layouts/landing.html
+  Inherits: root.html
+  Purpose: Create an engaging first impression for visitors discovering the site
+  
+  Template Logic:
+  - Hero section with clear value proposition
+  - Feature highlights with visual appeal
+  - Quick navigation to key areas
+  - Professional presentation with Bootstrap components
+  - Mobile-responsive design for all devices
+  
+  Layout Features:
+  - Hero banner with call-to-action
+  - Feature cards with icons and descriptions
+  - Quick start guide and navigation
+  - Social proof and credibility indicators
+  - Clean, professional aesthetic
+  
+  Target Audience:
+  - First-time visitors exploring the repository
+  - Developers looking for Jekyll themes
+  - Users seeking Docker-optimized solutions
+  - People interested in error-free development
+  
+  Conversion Goals:
+  - Encourage exploration of documentation
+  - Drive adoption of the theme
+  - Build trust through professional presentation
+  - Guide users to relevant resources
   
-  {{ content }}
+  Dependencies:
+  - Bootstrap 5 components and utilities
+  - Custom CSS for enhanced styling
+  - Responsive images and icons
+  ===================================================================
+-->
+
+<!-- ================================ -->
+<!-- HERO SECTION                     -->
+<!-- ================================ -->
+<div class="bg-primary text-white">
+    <div class="container-xl py-5 px-4 px-md-5">
+        <div class="row align-items-center min-vh-50 g-4 g-lg-5">
+            <div class="col-lg-6">
+                <h1 class="display-4 fw-bold mb-3">{{ page.title }}</h1>
+                <p class="lead mb-4">{{ page.description }}</p>
+                <div class="d-flex flex-column flex-md-row gap-3">
+                    <a href="#get-started" class="btn btn-light btn-lg">
+                        <i class="bi bi-rocket-takeoff me-2"></i>Get Started
+                    </a>
+                    <a href="#features" class="btn btn-outline-light btn-lg">
+                        <i class="bi bi-list-check me-2"></i>Features
+                    </a>
+                    <a href="{{ site.resources.github_repo }}" class="btn btn-outline-light btn-lg">
+                        <i class="bi bi-github me-2"></i>GitHub
+                    </a>
+                </div>
+            </div>
+            <div class="col-lg-6 text-center">
+                {% if page.hero_image %}
+                <img src="{{ page.hero_image }}" alt="{{ page.title }}" class="img-fluid rounded shadow-lg">
+                {% else %}
+                <div class="bg-light rounded p-5 text-dark">
+                    <i class="bi bi-code-square display-1"></i>
+                    <p class="mt-3 mb-0">Jekyll Theme</p>
+                </div>
+                {% endif %}
+            </div>
+        </div>
+    </div>
+</div>
+
+<!-- ================================ -->
+<!-- MAIN CONTENT AREA               -->
+<!-- ================================ -->
+{% include landing/landing-quick-links.html %}
+
+<div class="container-xl py-5 px-4 px-md-5">
+    {{ content }}
+</div>
+
+<!-- ================================ -->
+<!-- FEATURES SECTION                 -->
+<!-- ================================ -->
+<div class="py-5 bg-body-tertiary" id="features">
+    <div class="container-xl px-4 px-md-5">
+        <div class="row text-center mb-5">
+            <div class="col-lg-8 mx-auto">
+        <h2 class="display-5 fw-bold text-body-emphasis">Why Choose zer0-mistakes?</h2>
+        <p class="lead text-body-secondary">Built for developers who value reliability, simplicity, and modern workflows</p>
+            </div>
+        </div>
+        
+        <div class="row g-4">
+            <div class="col-md-4">
+                <div class="card h-100 border-0 shadow-sm">
+                    <div class="card-body text-center p-4">
+                        <div class="bg-primary text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-3" style="width: 60px; height: 60px;">
+                            <i class="bi bi-shield-check fs-4"></i>
+                        </div>
+            <h5 class="card-title text-body-emphasis">Error-Free Development</h5>
+            <p class="card-text text-body-secondary">Built-in error handling and self-healing installation process ensures a smooth development experience.</p>
+                    </div>
+                </div>
+            </div>
+            
+            <div class="col-md-4">
+                <div class="card h-100 border-0 shadow-sm">
+                    <div class="card-body text-center p-4">
+                        <div class="bg-success text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-3" style="width: 60px; height: 60px;">
+                            <i class="bi bi-boxes fs-4"></i>
+                        </div>
+            <h5 class="card-title text-body-emphasis">Docker-First Approach</h5>
+            <p class="card-text text-body-secondary">Cross-platform compatibility with zero local configuration. Works on Apple Silicon, Intel, and Linux.</p>
+                    </div>
+                </div>
+            </div>
+            
+            <div class="col-md-4">
+                <div class="card h-100 border-0 shadow-sm">
+                    <div class="card-body text-center p-4">
+                        <div class="bg-info text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-3" style="width: 60px; height: 60px;">
+                            <i class="bi bi-lightning-charge fs-4"></i>
+                        </div>
+            <h5 class="card-title text-body-emphasis">AI-Powered Setup</h5>
+            <p class="card-text text-body-secondary">Intelligent installation automation that detects and fixes common issues automatically.</p>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
 </div>
 
-<!-- Features -->
-    <!-- particles.js -->
-    <script src="/assets/js/particles-source.js"></script>
-    <script src="/assets/js/particles.js"></script>
+<!-- ================================ -->
+<!-- QUICK START SECTION             -->
+<!-- ================================ -->
+<div class="container-xl py-5 px-4 px-md-5" id="get-started">
+    <div class="row">
+        <div class="col-12 col-xl-10 mx-auto text-center">
+            <h2 class="display-5 fw-bold mb-4">Ready to Get Started?</h2>
+            <p class="lead mb-4">Choose your preferred installation method and be up and running in minutes</p>
+            {% include landing/landing-install-cards.html %}
+        </div>
+    </div>
+</div>

data/_layouts/root.html

@@ -1,54 +1,89 @@
 ---
 ---
 <!--
-  Zer0 Mistakes Jekyll Theme version 0.1 by Amr Abdel-Motaleb
-  Copyright 2024 Amr Abdel-Motaleb - it-journey.com | @bamr87
--->
-
-<!--
-  file: root.html
-  path:_layouts/root.html 
-  includes: head.html, google-tag-mgr.html, header.html, footer.html, algolia.html
+  ===================================================================
+  ROOT LAYOUT - Base template for the Zer0 Mistakes Jekyll Theme
+  ===================================================================
+  
+  File: root.html
+  Path: _layouts/root.html
+  Purpose: Base HTML structure that all other layouts inherit from
+  
+  Template Logic:
+  - Sets up the HTML document structure with Bootstrap 5 dark theme
+  - Includes essential meta tags and SEO optimization
+  - Loads external dependencies (CSS, JS, fonts)
+  - Provides the main content wrapper for child layouts
+  - Implements scroll spy for table of contents navigation
+  
+  Dependencies:
+  - head.html: Meta tags, stylesheets, and external resources
+  - svg.html: Inline SVG symbols for icons
+  - header.html: Main navigation and site branding
+  - info-section.html: Site-wide announcements or notices
+  - footer.html: Site footer with links and copyright
+  - js-cdn.html: JavaScript dependencies and custom scripts
+  
+  Theme: Zer0 Mistakes Jekyll Theme v0.1
+  Author: Amr Abdel-Motaleb
+  Copyright: 2024 - it-journey.com | @bamr87
+  ===================================================================
 -->
 
 <!doctype html>
-<html lang="{{ site.locale | slice: 0,2 | default: en }}" class="no-js" data-bs-theme="dark">
+<html lang="{{ site.locale | slice: 0,2 | default: 'en' }}" class="no-js" data-bs-theme="dark">
     <head>
-        <!-- _includes/head.html  -->
-        {% include head.html %}
+        <!-- =============================================== -->
+        <!-- HEAD SECTION: Meta tags, styles, and SEO setup -->
+        <!-- =============================================== -->
+        
+        <!-- Core site metadata, stylesheets, and external dependencies -->
+        {% include core/head.html %}
 
-        <!-- Jekyll-SEO Plugin https://github.com/jekyll/jekyll-seo-tag-->
+        <!-- Jekyll SEO plugin for enhanced search engine optimization -->
+        <!-- Documentation: https://github.com/jekyll/jekyll-seo-tag -->
         {% seo %}
-
     </head>
+    
     <body data-bs-spy="scroll" data-bs-target="#TableOfContents">
+        <!-- ============================================== -->
+        <!-- BODY SECTION: Site structure and content area -->
+        <!-- ============================================== -->
+        
+        <!-- Inline SVG symbols for consistent iconography throughout the site -->
+        {% include components/svg.html %}
 
-        <!-- _includes/svg.html -->
-        {% include svg.html %}
-
-        <!-- _includes/google-tag-manager-body.html - SEO -->
-
+        <!-- Google Tag Manager body code for analytics (if configured) -->
+        <!-- Note: Currently commented out - uncomment when GTM is needed -->
 
-        <!-- _includes/header.html - Header section with main Navigation and Search engine -->
-        {% include header.html %}
+        <!-- Main site header with navigation, branding, and search functionality -->
+        {% include core/header.html %}
 
-        {% include info-section.html %}
+        <!-- Site-wide information banner or announcement section -->
+        {% include components/info-section.html %}
 
-        <!-- Content -->
+        <!-- ======================== -->
+        <!-- MAIN CONTENT AREA        -->
+        <!-- ======================== -->
+        <!-- This is where child layouts inject their specific content -->
         <div>
             {{ content }}
         </div>
 
-        <!-- _include/footer.html -->
-        {%- include footer.html -%}
+        <!-- ======================== -->
+        <!-- FOOTER AND SCRIPTS       -->
+        <!-- ======================== -->
+        
+        <!-- Site footer with links, copyright, and additional navigation -->
+        {%- include core/footer.html -%}
 
-        <!-- Javascript scripts -->
+        <!-- JavaScript dependencies and custom scripts -->
         <div>
-            <!-- Search Engine  -->
-            <!-- _include/algolia.html -->
+            <!-- Search functionality (Algolia or similar) -->
+            <!-- Note: Currently commented out - uncomment when search is implemented -->
 
-            <!-- Javascript CDN -->
-            {% include js-cdn.html %}
+            <!-- External JavaScript libraries and custom scripts -->
+            {% include components/js-cdn.html %}
         </div>
     </body>
- </html>
+</html>

data/assets/js/back-to-top.js

@@ -1,24 +1,21 @@
-document.addEventListener('DOMContentLoaded', (event) => {
-  let mybutton = document.getElementById("backToTopBtn");
+document.addEventListener('DOMContentLoaded', () => {
+  const btn = document.getElementById('backToTopBtn');
+  if (!btn) return;
 
-  function topFunction() {
-    document.body.scrollTop = 0; // For Safari
-    document.documentElement.scrollTop = 0; // For Chrome, Firefox, IE and Opera
-    mybutton.style.opacity = "75%";
-  }
+  // Smooth scroll to top and keep accessible
+  const scrollToTop = (e) => {
+    if (e) e.preventDefault();
+    window.scrollTo({ top: 0, behavior: 'smooth' });
+  };
 
-  if (mybutton) {
-    mybutton.onclick = topFunction;
-  }
+  btn.addEventListener('click', scrollToTop);
 
-  // When the user scrolls down 20px from the top of the document, show the button
-  window.onscroll = function() {scrollFunction()};
+  const toggle = () => {
+    const y = window.scrollY || document.documentElement.scrollTop || document.body.scrollTop || 0;
+    btn.style.display = y > 200 ? 'block' : 'none';
+  };
 
-  function scrollFunction() {
-    if (document.body.scrollTop > 20 || document.documentElement.scrollTop > 20) {
-      mybutton.style.display = "block";
-    } else {
-      mybutton.style.display = "none";
-    }
-  }
+  // Initialize state and bind listener without clobbering
+  toggle();
+  window.addEventListener('scroll', toggle, { passive: true });
 });