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¶

Create a statistics page using the stats layout:

---
title: "Site Statistics Portal"
description: "Comprehensive analytics and metrics"
layout: stats
permalink: /stats/
---
Your additional content here (optional).

Ensure you have a statistics data file at _data/content_statistics.yml with the following structure:

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:

Create a new include file in _includes/stats/:

<!-- _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>

Include it in the stats layout:

<!-- 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:

Modifying CSS variables in assets/css/stats.css
Overriding Bootstrap classes with custom styles
Adding new utility classes for specific needs

Data Source Customization¶

The layout expects data from site.data.content_statistics. You can:

Change the data source by modifying the Liquid template references
Add new data fields to the YAML structure
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¶

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
Styling issues
Verify assets/css/stats.css is included
Check for CSS conflicts with other stylesheets
Ensure Bootstrap 5 is properly loaded
JavaScript errors
Check browser console for error messages
Verify Bootstrap JS is loaded
Ensure no conflicting JavaScript libraries

Performance Optimization¶

Large datasets
Implement pagination for large category/tag lists
Use lazy loading for secondary statistics
Consider caching generated statistics
Mobile optimization
Test on various device sizes
Optimize touch interactions
Minimize data transfer on mobile

Examples¶

Basic Statistics Page¶

---
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¶

---
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:

Interactive Charts: D3.js or Chart.js integration
Real-time Updates: WebSocket-based live statistics
Advanced Filters: Date ranges, category filters
Export Functionality: PDF and CSV export options
Comparison Views: Period-over-period comparisons
Custom Dashboards: User-configurable statistics views

Contributing¶

To contribute improvements to the statistics layout:

Follow the established file structure
Maintain Bootstrap 5 compatibility
Include proper documentation
Test across multiple browsers
Ensure accessibility compliance

For more information, see the main theme documentation.