jekyll-theme-zer0 0.2.1 → 0.5.0

data/_includes/core/head.html

@@ -47,10 +47,10 @@
 <!-- THIRD PARTY INTEGRATIONS        -->
 <!-- ================================ -->
 
-<!-- Mermaid Diagrams - Currently disabled for performance -->
-<!-- Enable for pages requiring diagram generation -->
-<!-- <script src="https://cdn.jsdelivr.net/npm/mermaid@8/dist/mermaid.min.js"></script>
-     <script>mermaid.initialize({ startOnLoad: true });</script> -->
+<!-- Mermaid Diagrams - Conditional loading based on page front matter -->
+{% if page.mermaid %}
+  {% include components/mermaid.html %}
+{% endif %}
 
 <!-- Nano Progress Bar - Visual loading indicator -->
 <script src="{{'/assets/js/nanobar.min.js' | relative_url }}"></script>
@@ -147,6 +147,11 @@
 <!-- Custom CSS overrides - Theme customizations and tweaks -->
 <link rel="stylesheet" href="{{'/assets/css/custom.css' | relative_url }}">
 
+<!-- Statistics page specific styles -->
+{% if page.layout == 'stats' %}
+<link rel="stylesheet" href="{{ '/assets/css/stats.css' | relative_url }}">
+{% endif %}
+
 <!-- ========================== -->
 <!-- EXPERIMENTAL FRAMEWORKS   -->
 <!-- ========================== -->

data/_includes/navigation/navbar.html

@@ -28,6 +28,9 @@
                             href="{{ link.url | relative_url }}"
                             {%- if link.url == page.url -%} aria-current="page"{%- endif -%}
                         >
+                            {%- if link.icon -%}
+                                <i class="{{site.default_icon}} {{ link.icon }} me-2"></i>
+                            {%- endif -%}
                             {{ link.title }}
                         </a>
 
@@ -65,6 +68,9 @@
                             href="{{ link.url | relative_url }}"
                             {%- if link.url == page.url -%} aria-current="page"{%- endif -%}
                         >
+                            {%- if link.icon -%}
+                                <i class="{{site.default_icon}} {{ link.icon }} me-2"></i>
+                            {%- endif -%}
                             {{ link.title }}
                         </a>
                     </li>

data/_includes/stats/README.md

@@ -0,0 +1,273 @@
+# Statistics Layout Documentation
+
+## Overview
+
+The Zer0-Mistakes theme now includes a comprehensive statistics layout system that provides detailed analytics and metrics for Jekyll sites. This system consists of a dedicated layout and modular include components that can be easily customized and extended.
+
+## Files Structure
+
+```
+_layouts/
+└── stats.html                      # Main statistics layout
+
+_includes/stats/
+├── stats-header.html               # Page header and navigation
+├── stats-overview.html             # Overview metrics cards
+├── stats-categories.html           # Categories analysis
+├── stats-tags.html                 # Tags analysis and tag cloud
+├── stats-metrics.html              # Additional metrics and facts
+└── stats-no-data.html              # Error state for missing data
+
+assets/css/
+└── stats.css                       # Statistics-specific styles
+```
+
+## Usage
+
+### Basic Setup
+
+1. Create a statistics page using the stats layout:
+
+```yaml
+---
+title: "Site Statistics Portal"
+description: "Comprehensive analytics and metrics"
+layout: stats
+permalink: /stats/
+---
+
+Your additional content here (optional).
+```
+
+2. Ensure you have a statistics data file at `_data/content_statistics.yml` with the following structure:
+
+```yaml
+generated_at: "2025-01-27 10:30:00"
+total_posts: 150
+categories:
+  - ["development", 45]
+  - ["tutorials", 32]
+  - ["guides", 28]
+tags:
+  - ["javascript", 25]
+  - ["python", 20]
+  - ["web-development", 18]
+```
+
+### Components Overview
+
+#### stats-header.html
+- Displays page title and description
+- Shows last update timestamp
+- Provides navigation breadcrumbs
+- Includes quick jump links to sections
+
+#### stats-overview.html
+- Four key metric cards (Posts, Categories, Tags, Data Status)
+- Color-coded cards with Bootstrap styling
+- Data freshness indicators
+- Summary bar below cards
+
+#### stats-categories.html
+- Top categories list with post counts
+- Activity level indicators
+- Summary statistics footer
+- Expandable interface for large datasets
+
+#### stats-tags.html
+- Top tags list with usage counts
+- Interactive tag cloud visualization
+- Dynamic font sizing based on usage
+- Hover effects and tooltips
+
+#### stats-metrics.html
+- Content overview section
+- Top performers analysis
+- Data health indicators
+- Action buttons (print, refresh, help)
+- Help modal with instructions
+
+#### stats-no-data.html
+- Error state when data is missing
+- Clear instructions for generating statistics
+- Troubleshooting information
+- Alternative navigation options
+
+## Customization
+
+### Adding New Sections
+
+To add a new statistics section:
+
+1. Create a new include file in `_includes/stats/`:
+
+```html
+<!-- _includes/stats/stats-new-section.html -->
+<div class="card shadow-sm">
+  <div class="card-header bg-purple text-white">
+    <h3 class="mb-0 fw-bold">
+      <i class="bi bi-new-icon me-2"></i> New Section
+    </h3>
+  </div>
+  <div class="card-body">
+    <!-- Your content here -->
+  </div>
+</div>
+```
+
+2. Include it in the stats layout:
+
+```html
+<!-- In _layouts/stats.html -->
+{% include stats/stats-new-section.html %}
+```
+
+### Styling Customization
+
+The stats layout uses Bootstrap 5 classes extensively. You can customize the appearance by:
+
+1. **Modifying CSS variables** in `assets/css/stats.css`
+2. **Overriding Bootstrap classes** with custom styles
+3. **Adding new utility classes** for specific needs
+
+### Data Source Customization
+
+The layout expects data from `site.data.content_statistics`. You can:
+
+1. **Change the data source** by modifying the Liquid template references
+2. **Add new data fields** to the YAML structure
+3. **Create multiple data sources** for different statistics types
+
+## Features
+
+### Responsive Design
+- Mobile-first approach
+- Responsive grid layouts
+- Touch-friendly interactions
+- Optimized for all screen sizes
+
+### Accessibility
+- ARIA labels and roles
+- Keyboard navigation support
+- Screen reader compatibility
+- High contrast mode support
+
+### Performance
+- Lazy loading of non-critical elements
+- Optimized CSS delivery
+- Minimal JavaScript footprint
+- Print-optimized styles
+
+### Interactive Elements
+- Hover effects on cards and tags
+- Smooth animations and transitions
+- Modal dialogs for additional information
+- Progress bars with dynamic updates
+
+## Browser Support
+
+The statistics layout supports all modern browsers:
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+## Dependencies
+
+- Jekyll 4.0+
+- Bootstrap 5.3.3
+- Bootstrap Icons 1.10.3
+- Modern browser with CSS Grid support
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Statistics not displaying**
+   - Check that `_data/content_statistics.yml` exists
+   - Verify the YAML structure matches the expected format
+   - Ensure the data generation script has run successfully
+
+2. **Styling issues**
+   - Verify `assets/css/stats.css` is included
+   - Check for CSS conflicts with other stylesheets
+   - Ensure Bootstrap 5 is properly loaded
+
+3. **JavaScript errors**
+   - Check browser console for error messages
+   - Verify Bootstrap JS is loaded
+   - Ensure no conflicting JavaScript libraries
+
+### Performance Optimization
+
+1. **Large datasets**
+   - Implement pagination for large category/tag lists
+   - Use lazy loading for secondary statistics
+   - Consider caching generated statistics
+
+2. **Mobile optimization**
+   - Test on various device sizes
+   - Optimize touch interactions
+   - Minimize data transfer on mobile
+
+## Examples
+
+### Basic Statistics Page
+
+```markdown
+---
+title: "Site Analytics"
+description: "Comprehensive site statistics and metrics"
+layout: stats
+permalink: /analytics/
+---
+
+This page provides detailed analytics about our content library.
+```
+
+### Custom Statistics with Additional Content
+
+```markdown
+---
+title: "Content Metrics Dashboard"
+description: "Advanced analytics for content creators"
+layout: stats
+permalink: /metrics/
+---
+
+## Content Performance Insights
+
+Our analytics system tracks various metrics to help understand content performance and user engagement.
+
+### Key Metrics
+- Content reach and engagement
+- Category performance trends
+- Tag effectiveness analysis
+- User interaction patterns
+
+### Data Collection
+Statistics are updated daily and include all published content from the past 12 months.
+```
+
+## Future Enhancements
+
+Planned improvements for the statistics layout:
+
+1. **Interactive Charts**: D3.js or Chart.js integration
+2. **Real-time Updates**: WebSocket-based live statistics
+3. **Advanced Filters**: Date ranges, category filters
+4. **Export Functionality**: PDF and CSV export options
+5. **Comparison Views**: Period-over-period comparisons
+6. **Custom Dashboards**: User-configurable statistics views
+
+## Contributing
+
+To contribute improvements to the statistics layout:
+
+1. Follow the established file structure
+2. Maintain Bootstrap 5 compatibility
+3. Include proper documentation
+4. Test across multiple browsers
+5. Ensure accessibility compliance
+
+For more information, see the main theme documentation.

data/_includes/stats/stats-categories.html

@@ -0,0 +1,146 @@
+<!--
+  ===================================================================
+  STATS CATEGORIES COMPONENT
+  ===================================================================
+  
+  File: stats-categories.html
+  Path: _includes/stats/stats-categories.html
+  Purpose: Categories analysis section for statistics dashboard
+  
+  Features:
+  - Top categories list with post counts
+  - Bootstrap styled card layout
+  - Responsive badges for counts
+  - Sortable category data
+  
+  Dependencies:
+  - Bootstrap 5 for styling
+  - Bootstrap Icons for iconography
+  - site.data.content_statistics.categories
+  ===================================================================
+-->
+
+<!-- ================================================ -->
+<!-- CATEGORIES ANALYSIS SECTION                     -->
+<!-- Top categories with post counts                 -->
+<!-- ================================================ -->
+<div id="categories" class="card shadow-sm h-100">
+  <div class="card-header bg-primary text-white">
+    <div class="d-flex align-items-center justify-content-between">
+      <h3 class="mb-0 fw-bold">
+        <i class="bi bi-folder2-open me-2"></i> Top Categories
+      </h3>
+      <span class="badge bg-light text-primary">
+        {{ site.data.content_statistics.overview.total_categories | default: 0 }}
+      </span>
+    </div>
+  </div>
+  
+  <div class="card-body p-0">
+    {% if site.data.content_statistics.categories and site.data.content_statistics.categories.size > 0 %}
+      
+      <!-- Categories List -->
+      <div class="list-group list-group-flush">
+        {% for category in site.data.content_statistics.categories limit: 15 %}
+          <div class="list-group-item d-flex justify-content-between align-items-center py-3">
+            <div class="d-flex align-items-center">
+              <i class="bi bi-folder text-primary me-3"></i>
+              <div>
+                <span class="fw-medium">{{ category[0] | capitalize }}</span>
+                {% assign max_category = site.data.content_statistics.categories | first %}
+                {% assign max_count = max_category[1] | default: 1 %}
+                {% assign high_threshold = max_count | times: 0.7 | round %}
+                {% assign medium_threshold = max_count | times: 0.4 | round %}
+                {% if category[1] >= high_threshold and category[1] > 2 %}
+                  <br><small class="text-muted">High activity</small>
+                {% elsif category[1] >= medium_threshold and category[1] > 1 %}
+                  <br><small class="text-muted">Medium activity</small>
+                {% else %}
+                  <br><small class="text-muted">Low activity</small>
+                {% endif %}
+              </div>
+            </div>
+            <div class="text-end">
+              <span class="badge bg-primary rounded-pill fs-6 px-3 py-2">
+                {{ category[1] }}
+              </span>
+              <br><small class="text-muted">posts</small>
+            </div>
+          </div>
+        {% endfor %}
+      </div>
+      
+      <!-- Show More Button if there are more categories -->
+      {% if site.data.content_statistics.categories.size > 15 %}
+        <div class="card-footer bg-light text-center">
+          <button class="btn btn-outline-primary btn-sm" 
+                  onclick="toggleAllCategories(this)">
+            <i class="bi bi-chevron-down"></i>
+            Show {{ site.data.content_statistics.categories.size | minus: 15 }} more categories
+          </button>
+        </div>
+      {% endif %}
+      
+    {% else %}
+      
+      <!-- No Categories Available -->
+      <div class="text-center py-5">
+        <i class="bi bi-folder-x display-4 text-muted mb-3"></i>
+        <h5 class="text-muted">No categories found</h5>
+        <p class="text-muted">Categories will appear here once content is categorized.</p>
+      </div>
+      
+    {% endif %}
+  </div>
+  
+  <!-- Categories Summary Footer -->
+  {% if site.data.content_statistics.categories and site.data.content_statistics.categories.size > 0 %}
+    <div class="card-footer bg-light">
+      <div class="row text-center">
+        <div class="col-4">
+          <strong class="text-primary">{{ site.data.content_statistics.overview.total_categories | default: 0 }}</strong>
+          <br><small class="text-muted">Total</small>
+        </div>
+        <div class="col-4">
+          {% assign top_category = site.data.content_statistics.categories | first %}
+          <strong class="text-success">{{ top_category[1] | default: 0 }}</strong>
+          <br><small class="text-muted">Most Posts</small>
+        </div>
+        <div class="col-4">
+          {% assign total_posts = 0 %}
+          {% for category in site.data.content_statistics.categories %}
+            {% assign total_posts = total_posts | plus: category[1] %}
+          {% endfor %}
+          {% assign avg_posts = total_posts | divided_by: site.data.content_statistics.categories.size %}
+          <strong class="text-info">{{ avg_posts | default: 0 }}</strong>
+          <br><small class="text-muted">Avg Posts</small>
+        </div>
+      </div>
+    </div>
+  {% endif %}
+</div>
+
+<!-- ================================================ -->
+<!-- CATEGORIES JAVASCRIPT                           -->
+<!-- Interactive functionality for categories        -->
+<!-- ================================================ -->
+<script>
+function toggleAllCategories(button) {
+  // This would expand/collapse additional categories
+  // Implementation depends on whether you want to load more data
+  // or show/hide existing elements
+  
+  const icon = button.querySelector('i');
+  const isExpanded = icon.classList.contains('bi-chevron-up');
+  
+  if (isExpanded) {
+    icon.className = 'bi bi-chevron-down';
+    button.innerHTML = '<i class="bi bi-chevron-down"></i> Show more categories';
+  } else {
+    icon.className = 'bi bi-chevron-up';
+    button.innerHTML = '<i class="bi bi-chevron-up"></i> Show fewer categories';
+  }
+  
+  // Add your expand/collapse logic here
+}
+</script>

data/_includes/stats/stats-header.html

@@ -0,0 +1,123 @@
+<!--
+  ===================================================================
+  STATS HEADER COMPONENT - BOOTSTRAP 5 OPTIMIZED
+  ===================================================================
+  
+  File: stats-header.html
+  Path: _includes/stats/stats-header.html
+  Purpose: Page header for statistics dashboard using Bootstrap 5 classes
+  
+  Features:
+  - Bootstrap 5 utility classes for layout and styling
+  - Responsive design with Bootstrap breakpoints
+  - Bootstrap icons and color system
+  - Minimal custom CSS dependencies
+  
+  Dependencies:
+  - Bootstrap 5 for styling
+  - Bootstrap Icons for iconography
+  - Jekyll data variables
+  ===================================================================
+-->
+
+<!-- ================================================ -->
+<!-- STATS PAGE HEADER                               -->
+<!-- Title, description, and metadata display        -->
+<!-- ================================================ -->
+<div class="row mb-5">
+  <div class="col-12">
+    <div class="text-center mb-4">
+      <!-- Header Icon with Bootstrap classes -->
+      <div class="d-inline-flex align-items-center justify-content-center bg-primary bg-gradient rounded-circle p-4 mb-4 shadow-lg stats-header-icon">
+        <i class="bi bi-graph-up fs-1 text-white stats-icon-rotate"></i>
+      </div>
+      
+      <!-- Title with Bootstrap typography -->
+      <h1 class="display-3 mb-3 fw-bold text-primary">
+        {{ page.title | default: "Site Statistics Portal" }}
+      </h1>
+      
+      <!-- Description with Bootstrap lead class -->
+      <p class="lead text-muted mb-4 fs-4">
+        {{ page.description | default: "Comprehensive analytics and insights from the knowledge base" }}
+      </p>
+    </div>
+    
+    <!-- Last Updated Information using Bootstrap alerts -->
+    {% if site.data.content_statistics and site.data.content_statistics.generated_at %}
+      <div class="alert alert-info border-0 bg-gradient shadow-sm d-flex align-items-center justify-content-between" role="alert">
+        <div class="d-flex align-items-center">
+          <i class="bi bi-clock me-3 fs-4"></i>
+          <span class="fw-medium">
+            <strong>Last updated:</strong> 
+            {{ site.data.content_statistics.generated_at | date: "%B %d, %Y at %I:%M %p" }}
+          </span>
+        </div>
+        <button class="btn btn-outline-info btn-sm" onclick="window.location.reload()">
+          <i class="bi bi-arrow-clockwise me-1"></i>
+          Refresh
+        </button>
+      </div>
+    {% else %}
+      <div class="alert alert-warning border-0 bg-gradient shadow-sm d-flex align-items-center justify-content-between" role="alert">
+        <div class="d-flex align-items-center">
+          <i class="bi bi-exclamation-triangle me-3 fs-4"></i>
+          <span class="fw-medium">
+            <strong>Statistics not yet generated.</strong> 
+            Run <code class="bg-light text-dark px-2 py-1 rounded">ruby _data/generate_statistics.rb</code> to create statistics.
+          </span>
+        </div>
+        <button class="btn btn-outline-warning btn-sm" onclick="window.location.reload()">
+          <i class="bi bi-arrow-clockwise me-1"></i>
+          Check Again
+        </button>
+      </div>
+    {% endif %}
+  </div>
+</div>
+
+<!-- ================================================ -->
+<!-- STATS NAVIGATION BREADCRUMBS                    -->
+<!-- Quick navigation within the stats page          -->
+<!-- ================================================ -->
+<div class="row mb-5">
+  <div class="col-12">
+    <!-- Bootstrap breadcrumb -->
+    <nav aria-label="Statistics navigation">
+      <ol class="breadcrumb bg-light p-3 rounded shadow-sm">
+        <li class="breadcrumb-item">
+          <a href="{{ '/' | relative_url }}" class="text-decoration-none">
+            <i class="bi bi-house me-1"></i> Home
+          </a>
+        </li>
+        <li class="breadcrumb-item active fw-medium" aria-current="page">
+          <i class="bi bi-graph-up me-1"></i> Statistics
+        </li>
+      </ol>
+    </nav>
+    
+    <!-- Quick Jump Navigation using Bootstrap button group -->
+    {% if site.data.content_statistics %}
+      <div class="text-center">
+        <div class="btn-group btn-group-lg shadow-sm d-flex flex-wrap gap-2" role="group" aria-label="Statistics navigation">
+          <a href="#overview" class="btn btn-outline-primary flex-fill">
+            <i class="bi bi-speedometer2 me-1"></i> 
+            <span class="d-none d-sm-inline">Overview</span>
+          </a>
+          <a href="#categories" class="btn btn-outline-success flex-fill">
+            <i class="bi bi-folder me-1"></i> 
+            <span class="d-none d-sm-inline">Categories</span>
+          </a>
+          <a href="#tags" class="btn btn-outline-info flex-fill">
+            <i class="bi bi-tags me-1"></i> 
+            <span class="d-none d-sm-inline">Tags</span>
+          </a>
+          <a href="#metrics" class="btn btn-outline-warning flex-fill">
+            <i class="bi bi-info-circle me-1"></i> 
+            <span class="d-none d-sm-inline">Metrics</span>
+          </a>
+        </div>
+      </div>
+    {% endif %}
+  </div>
+</div>