jekyll-theme-zer0 0.1.8 → 0.2.1

data/_includes/core/header.html

@@ -0,0 +1,125 @@
+<!--
+  ===================================================================
+  HEADER - Main Navigation and Site Header
+  ===================================================================
+  
+  File: header.html
+  Path: _includes/header.html
+  Purpose: Primary site navigation with responsive design and 
+           offcanvas mobile menu integration
+  
+  Template Logic:
+  - Responsive navigation bar with Bootstrap 5 components
+  - Offcanvas sidebars for mobile navigation
+  - Brand logo and home navigation integration
+  - Settings modal and navigation toggles
+  
+  Dependencies:
+  - branding.html: Site title and logo display
+  - navbar.html: Main navigation menu items
+  - Bootstrap 5 offcanvas and navbar components
+  
+  Responsive Behavior:
+  - Desktop: Full horizontal navigation bar
+  - Mobile: Collapsed navigation with hamburger menu
+  - Offcanvas panels for sidebar and navigation
+  
+  TODO: Fix Nanobar progress bar positioning and animation
+  ===================================================================
+-->
+
+<header id="navbar" class="container-fluid text-center z-1" role="navigation">
+
+    <!-- ================================ -->
+    <!-- TOP NAVIGATION BAR              -->
+    <!-- ================================ -->
+    <div class="navbar navbar-expand-lg bg-body-tertiary flex-nowrap justify-content-center bottom-shadow">
+       
+        <!-- ========================== -->
+        <!-- PROGRESS BAR INDICATOR    -->
+        <!-- ========================== -->
+        <!-- Fixed position progress bar for page loading feedback -->
+        <div class="nanobar" id="top-progress-bar" style="position: fixed;">
+            <div class="bar"></div>
+        </div>
+        
+        <!-- ========================== -->
+        <!-- MAIN NAVIGATION CONTAINER -->
+        <!-- ========================== -->
+        <nav class="container-xl order-2 order-lg-1 grid gap-1">
+
+            <!-- ========================== -->
+            <!-- MOBILE MENU CONTROLS      -->
+            <!-- ========================== -->
+            
+            <!-- Left Sidebar Toggle - Mobile view only -->
+            <div class="bd-navbar-toggle">
+                <button class="navbar-toggler p-2" 
+                        type="button" 
+                        data-bs-toggle="offcanvas" 
+                        data-bs-target="#bdSidebar" 
+                        aria-controls="bdSidebar" 
+                        aria-label="Toggle navigation">
+                    <span class="bi bi-list"></span>
+                </button>
+            </div>
+
+            <!-- ========================== -->
+            <!-- BRAND AND HOME NAVIGATION -->
+            <!-- ========================== -->
+            <div class="container d-inline-flex text-center">
+                <!-- Home Navigation Button -->
+                {%- for home in site.data.navigation.home -%}
+                <a class="btn" href="{{ home.url | relative_url }}">
+                    <i class="{{ site.default_icon}} {{ home.icon }}"></i>
+                </a>
+                {% endfor %}
+                
+                <!-- Brand Logo Link to Root -->
+                <!-- Logo path configured in _config.yml -->
+                {% capture logo_path %}{{ site.logo }}{% endcapture %}
+                <a class="navbar-brand" href="{{ site.baseurl }}/">
+                    <img src="{{ logo_path | relative_url }}" alt="Logo" width="30" height="30">
+                </a>
+            </div>
+            
+            <!-- ========================== -->
+            <!-- SITE BRANDING SECTION     -->
+            <!-- ========================== -->
+            <!-- Site title and subtitle display -->
+            {% include core/branding.html %}
+    
+            <!-- ========================== -->
+            <!-- MAIN NAVIGATION MENU      -->
+            <!-- ========================== -->
+            <!-- Primary navigation items from _data/navigation.yml -->
+            {% include navigation/navbar.html %}
+
+            <!-- ========================== -->
+            <!-- UTILITY CONTROLS          -->
+            <!-- ========================== -->
+            
+            <!-- Settings Modal Toggle -->
+            <div class="btn"
+                data-bs-toggle="modal" 
+                data-bs-target="#info-section" 
+                aria-expanded="false" 
+                aria-controls="#info-section"
+                role="button">
+                <i type="button" class="{{site.default_icon}} bi-gear"></i>
+            </div>
+
+            <!-- Navigation Menu Toggle - Mobile view -->
+            <div class="bd-navbar-toggle">
+                <button class="navbar-toggler p-2" 
+                        type="button" 
+                        data-bs-toggle="offcanvas" 
+                        data-bs-target="#bdNavbar" 
+                        aria-controls="bdNavbar" 
+                        aria-label="Toggle navigation">
+                    <span class="bi bi-three-dots"></span>
+                </button>
+            </div>
+        </nav>
+    </div>
+</header>

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

@@ -0,0 +1,52 @@
+<!-- Installation method cards; uses site.resources.* and environment where helpful -->
+<div class="row g-4 justify-content-center">
+  <div class="col-12 col-sm-10 col-md-6 col-lg-4">
+    <div class="card h-100 border-0 shadow-sm">
+      <div class="card-header bg-primary text-white">
+        <h5 class="card-title mb-0"><i class="bi bi-gem me-2"></i>Ruby Gem</h5>
+      </div>
+      <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>
+      </div>
+    </div>
+  </div>
+  
+  <div class="col-12 col-sm-10 col-md-6 col-lg-4">
+    <div class="card h-100 border-0 shadow-sm">
+      <div class="card-header bg-info text-white">
+        <h5 class="card-title mb-0"><i class="bi bi-box-seam me-2"></i>Docker Image</h5>
+      </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>
+      </div>
+    </div>
+  </div>
+  
+  <div class="col-12 col-sm-10 col-md-6 col-lg-4">
+    <div class="card h-100 border-0 shadow-sm">
+      <div class="card-header bg-secondary text-white">
+        <h5 class="card-title mb-0"><i class="bi bi-git me-2"></i>Fork Repository</h5>
+      </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 }}
+cd {{ site.local_repo | default: site.repository_name | default: 'repo' }}
+git remote add upstream {{ site.resources.github_repo | 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>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- 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">
+    <i class="bi bi-journal-text me-2"></i>Read the Contributing Guide
+  </a>
+</div>

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

@@ -0,0 +1,28 @@
+<!-- Quick Links bar for landing page; uses site.resources config -->
+<div class="bg-dark text-white py-3">
+  <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">
+          <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">
+          <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">
+          <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">
+          <i class="bi bi-git me-2"></i> Fork Project
+        </a>
+      </div>
+    </div>
+  </div>
+  
+</div>

data/_includes/navigation/navbar.html

@@ -0,0 +1,96 @@
+<!-- 
+    file: navbar.html
+    path: /includes/navbar.html
+    includes:
+    purpose: Offcanvas main navigation following Bootstrap 5 best practices
+ -->
+
+<!-- Navigation Links - Offcanvas -->
+<div class="offcanvas offcanvas-end col-lg-2" tabindex="-1" id="bdNavbar" aria-labelledby="mainNavOffcanvasLabel">
+
+    <!-- Main Navigation Header - Offcanvas -->
+    <div class="offcanvas-header border-bottom">
+        <h5 class="offcanvas-title" id="mainNavOffcanvasLabel">Main Navigation</h5>
+        <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close" data-bs-target="#bdNavbar"></button>
+    </div>
+
+    <!-- Main Navigation Body - Offcanvas -->
+    <div class="offcanvas-body">
+        <ul class="navbar-nav justify-content-lg-center text-start flex-grow-1">
+            {%- for link in site.data.navigation.main -%}
+                {%- assign has_children = link.sublinks and link.sublinks.size > 0 -%}
+
+                {%- if has_children -%}
+                    <li class="nav-item dropdown d-flex align-items-center">
+                        <!-- Parent link navigates directly -->
+                        <a
+                            class="nav-link"
+                            href="{{ link.url | relative_url }}"
+                            {%- if link.url == page.url -%} aria-current="page"{%- endif -%}
+                        >
+                            {{ link.title }}
+                        </a>
+
+                        <!-- Split toggle opens the dropdown -->
+                        <a
+                            class="nav-link dropdown-toggle dropdown-toggle-split ms-2"
+                            href="#"
+                            id="dropdown-{{ link.title | slugify }}"
+                            role="button"
+                            data-bs-toggle="dropdown"
+                            aria-expanded="false"
+                            aria-label="Toggle {{ link.title }} menu"
+                        >
+                            <span class="visually-hidden">Toggle dropdown</span>
+                        </a>
+
+                        <ul class="dropdown-menu dropdown-menu-start w-100" aria-labelledby="dropdown-{{ link.title | slugify }}">
+                            {%- for sublink in link.sublinks -%}
+                                <li>
+                                    <a
+                                        class="dropdown-item"
+                                        href="{{ sublink.url | relative_url }}"
+                                        {%- if sublink.url == page.url -%} aria-current="page"{%- endif -%}
+                                    >
+                                        {{ sublink.title }}
+                                    </a>
+                                </li>
+                            {%- endfor -%}
+                        </ul>
+                    </li>
+                {%- else -%}
+                    <li class="nav-item">
+                        <a
+                            class="nav-link"
+                            href="{{ link.url | relative_url }}"
+                            {%- if link.url == page.url -%} aria-current="page"{%- endif -%}
+                        >
+                            {{ link.title }}
+                        </a>
+                    </li>
+                {%- endif -%}
+            {%- endfor -%}
+        </ul>
+    </div>
+</div>
+
+<!-- Script to handle offcanvas navigation -->
+<script>
+document.addEventListener('DOMContentLoaded', function() {
+    // Get all navigation links in the offcanvas
+    const offcanvasLinks = document.querySelectorAll('#bdNavbar .nav-link[href]:not(.dropdown-toggle), #bdNavbar .dropdown-item[href]');
+    
+    offcanvasLinks.forEach(link => {
+        link.addEventListener('click', function(e) {
+            // Allow the navigation to happen
+            // Then close the offcanvas after a brief delay
+            setTimeout(() => {
+                const offcanvas = bootstrap.Offcanvas.getInstance(document.getElementById('bdNavbar'));
+                if (offcanvas) {
+                    offcanvas.hide();
+                }
+            }, 100);
+        });
+    });
+});
+</script>

data/_includes/navigation/sidebar-left.html

@@ -0,0 +1,83 @@
+<!--
+  ===================================================================
+  SIDEBAR LEFT - Dynamic Navigation Sidebar
+  ===================================================================
+  
+  File: sidebar-left.html 
+  Path: _includes/sidebar-left.html
+  Purpose: Left sidebar navigation with multiple content modes including
+           dynamic page listing, category browsing, and manual navigation
+  
+  Template Logic:
+  - Responsive offcanvas sidebar for mobile devices
+  - Three navigation modes based on page.sidebar.nav:
+    * "dynamic": Auto-generated folder structure from pages
+    * "searchCats": Category-based navigation from site categories
+    * Manual: Predefined navigation from _data files
+  
+  Dependencies:
+  - sidebar-folders.html: Dynamic folder structure generation
+  - sidebar-categories.html: Category-based navigation
+  - nav_list.html: Manual navigation list rendering
+  - Bootstrap 5 offcanvas component
+  
+  Navigation Modes:
+  1. Dynamic: Scans site.pages for index.md files to build folder structure
+  2. Categories: Groups content by Jekyll categories
+  3. Manual: Uses predefined navigation from _data/navigation.yml
+  ===================================================================
+-->
+
+<!-- ================================ -->
+<!-- SIDEBAR NAVIGATION CONTAINER   -->
+<!-- ================================ -->
+<!-- Responsive offcanvas sidebar - full-width on mobile, fixed on desktop -->
+<div class="offcanvas-lg offcanvas-start" tabindex="-1" id="bdSidebar" aria-labelledby="bdSidebarOffcanvasLabel">
+
+  <!-- ========================== -->
+  <!-- SIDEBAR HEADER            -->
+  <!-- ========================== -->
+  <!-- Mobile-only header with close button -->
+  <div class="offcanvas-header border-bottom">
+    <h5 class="offcanvas-title" id="bdSidebarOffcanvasLabel">Browse docs</h5>
+    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close" data-bs-target="#bdSidebar"></button>
+  </div>
+
+  <!-- ========================== -->
+  <!-- SIDEBAR CONTENT AREA      -->
+  <!-- ========================== -->
+  <!-- Scrollable content area with dynamic navigation options -->
+  <div class="offcanvas-body overflow-auto">
+
+    <!-- ========================== -->
+    <!-- DYNAMIC PAGE LISTING      -->
+    <!-- ========================== -->
+    <!-- Auto-generates folder structure from pages containing index.md -->
+    {% if page.sidebar.nav == "dynamic" %}
+    <div class="list-group" id="sidebar-content">
+      {% assign folders = site.pages | where_exp: "item", "item.path contains 'index.md'" | sort: 'path' %}
+      {% include navigation/sidebar-folders.html folders=folders %}
+    </div>
+
+    <!-- ========================== -->
+    <!-- CATEGORY-BASED NAVIGATION -->
+    <!-- ========================== -->
+    <!-- Creates navigation from Jekyll post/page categories -->
+    {% elsif page.sidebar.nav == "searchCats" %}
+    <div class="list-group" id="sidebar-content">
+      {% assign categories = site.categories | sort %}
+      {% include navigation/sidebar-categories.html categories=categories %}
+    </div>
+    
+    <!-- ========================== -->
+    <!-- MANUAL NAVIGATION LIST    -->
+    <!-- ========================== -->
+    <!-- Uses predefined navigation structure from _data files -->
+    {% elsif page.sidebar.nav %}
+    <nav class="w-100">
+      {% include navigation/nav_list.html nav=page.sidebar.nav %}
+    </nav>
+    {% endif %}
+    
+  </div>
+</div>

data/_includes/{sidebar-right.html → navigation/sidebar-right.html}

@@ -1,7 +1,7 @@
 <!-- 
   file: sidebar-right.html 
   path: _includes/sidebar-right.html
-  includes: nav_list.html, toc.html
+  includes: nav_list.html, content/toc.html
 -->
 
 <!-- TOC button in mobile view  -->
@@ -32,16 +32,9 @@
     <!-- TOC list -->
 
     <!-- TOC list -->
-      {% include toc.html sanitize=true html=content h_min=1 h_max=3 class="list-group-flush" item_class="list-group-item" anchor_class="" skip_no_ids=true %}
+      {% include content/toc.html sanitize=true html=content h_min=1 h_max=3 class="list-group-flush" item_class="list-group-item" anchor_class="" skip_no_ids=true %}
     </nav>
   </div>
 </div>
-  <!-- Back to Top -->
-  <div>
-    <button onclick="topFunction()" id="backToTopBtn" title="Go to top">
-      <span class="arrow">&uarr;</span>
-      <span class="text">Back to Top</span>
-    </button>
-  </div>
+   
 
-  

data/_layouts/README.md

@@ -0,0 +1,198 @@
+# Layout Files Documentation
+
+This directory contains the Jekyll layout templates for the Zer0-Pages theme.  
+Each layout has been organized with comprehensive comments explaining the template logic,  
+structure, and usage patterns.
+
+## Layout Hierarchy
+
+```text
+root.html (base template)
+├── default.html (sidebar layout)
+│   ├── journals.html (blog posts)
+│   ├── collection.html (collection pages)
+│   └── javascript.html (JavaScript demos)
+├── home.html (homepage)
+├── blog.html (blog homepage)
+├── landing.html (landing pages)
+└── index.html (search pages)
+```
+
+## Layout Files Overview
+
+### 🏗️ Core Layouts
+
+#### `root.html`
+
+- **Purpose**: Base HTML structure for all pages
+- **Features**: Bootstrap 5 dark theme, SEO optimization, scroll spy
+- **Dependencies**: head.html, header.html, footer.html, js-cdn.html
+- **Usage**: Inherited by all other layouts
+
+#### `default.html`
+
+- **Purpose**: Standard content layout with sidebars
+- **Features**: Three-column responsive layout, navigation, table of contents
+- **Dependencies**: sidebar-left.html, intro.html, sidebar-right.html
+- **Usage**: Documentation pages, standard content
+
+### 📝 Content Layouts
+
+#### `journals.html`
+
+- **Purpose**: Blog post and article display
+- **Features**: Article structure, post navigation, comment system
+- **Dependencies**: giscus.html for comments
+- **Usage**: Individual blog posts and articles
+
+#### `collection.html`
+
+- **Purpose**: Collection listing with card grid
+- **Features**: Responsive cards, sorting, preview images
+- **Dependencies**: Bootstrap card components
+- **Usage**: Portfolio, projects, grouped content
+
+#### `blog.html`
+
+- **Purpose**: Magazine-style blog homepage
+- **Features**: Featured posts, sidebar, responsive design
+- **Dependencies**: sidebar-categories.html, navigation data
+- **Usage**: Blog index and homepage
+
+### 🎯 Specialized Layouts
+
+#### `home.html`
+
+- **Purpose**: Clean homepage template
+- **Features**: Minimal structure, RSS feed link
+- **Dependencies**: None
+- **Usage**: Site homepage, landing content
+
+#### `landing.html`
+
+- **Purpose**: Marketing pages with visual effects
+- **Features**: Particles.js background, offcanvas navigation
+- **Dependencies**: particles.js, sidebar-left.html
+- **Usage**: Product pages, campaigns, portfolios
+
+#### `index.html`
+
+- **Purpose**: Search and indexing pages
+- **Features**: Full-width container, search optimization
+- **Dependencies**: Search engine integration
+- **Usage**: Search results, site indexes
+
+#### `javascript.html`
+
+- **Purpose**: JavaScript demonstration pages
+- **Features**: Interactive elements, code examples
+- **Dependencies**: Custom JavaScript functions
+- **Usage**: Tutorials, interactive demos
+
+## Comment Organization Standards
+
+Each layout file now includes:
+
+### 1. Header Documentation Block
+
+```html
+<!--
+  ===================================================================
+  LAYOUT NAME - Brief description
+  ===================================================================
+  
+  File: filename.html
+  Path: _layouts/filename.html
+  Inherits: parent-layout.html
+  Purpose: Detailed purpose explanation
+  
+  Template Logic:
+  - Key functionality points
+  - Responsive behavior
+  - Content organization
+  
+  Dependencies:
+  - Include files used
+  - External libraries
+  - Required data/configuration
+  ===================================================================
+-->
+```
+
+### 2. Section Comments
+
+```html
+<!-- ================================ -->
+<!-- SECTION NAME                     -->
+<!-- ================================ -->
+<!-- Description of what this section does -->
+```
+
+### 3. Subsection Comments
+
+```html
+<!-- ========================== -->
+<!-- SUBSECTION NAME            -->
+<!-- ========================== -->
+<!-- Specific functionality notes -->
+```
+
+### 4. Inline Comments
+
+```html
+<!-- Explain complex logic or conditional statements -->
+{% if condition %}
+    <!-- Why this condition exists and what it affects -->
+{% endif %}
+```
+
+## Template Logic Patterns
+
+### Conditional Content Display
+
+- Use descriptive comments for complex conditionals
+- Explain the business logic behind template decisions
+- Document fallback behaviors
+
+### Loop Processing
+
+- Explain data source and filtering logic
+- Document sorting and limiting operations
+- Note performance considerations
+
+### Include Integration
+
+- Document which includes are used and why
+- Explain parameter passing to includes
+- Note dependencies between includes
+
+### Bootstrap Integration
+
+- Document responsive behavior
+- Explain grid system usage
+- Note accessibility considerations
+
+## Best Practices
+
+1. **Documentation First**: Every layout should be self-documenting
+2. **Consistent Structure**: Follow the established comment hierarchy
+3. **Explain Intent**: Don't just describe what code does, explain why
+4. **Update Comments**: Keep documentation current with code changes
+5. **Template Logic**: Explain complex Liquid template operations
+6. **Dependencies**: Document all external dependencies and includes
+7. **Responsive Design**: Note mobile/desktop behavior differences
+8. **Performance**: Comment on loading order and optimization
+
+## Maintenance Guidelines
+
+- Update comments when modifying layouts
+- Test responsive behavior across devices
+- Validate HTML5 semantic structure
+- Check accessibility compliance
+- Monitor Bootstrap version compatibility
+- Update documentation for new features
+
+---
+
+*These layouts follow the Zer0-Mistakes theme standards for maintainable,  
+documented, and responsive Jekyll templates.*