Statistics Dashboard Feature

By Amr

Comprehensive site analytics and content metrics system for Jekyll themes

Estimated reading time: 6 minutes

Edit on GitHub

Statistics Dashboard Feature

The Zer0-Mistakes theme now includes a comprehensive statistics dashboard that provides real-time analytics and insights about your Jekyll site’s content.

Overview

The Statistics Dashboard is a modular, responsive analytics system that automatically analyzes your site’s content and presents meaningful metrics through an interactive Bootstrap 5-based interface.

Key Features

  • 📊 Real-time Content Analysis: Automatic scanning of posts, pages, and collections
  • 🎯 Intelligent Categorization: Smart activity level calculations based on actual usage
  • 📱 Responsive Design: Mobile-first approach with Bootstrap 5 components
  • 🔧 Modular Architecture: Six specialized components for maintainable code
  • ⚡ Performance Optimized: Minimal custom CSS, leveraging Bootstrap utilities
  • ♿ Accessibility Compliant: ARIA support and screen reader compatibility

What’s Included

Core Components

1. Statistics Layout (_layouts/stats.html)

  • Main container for the dashboard
  • Handles data validation and error states
  • Includes JavaScript for animations and interactions

2. Header Component (_includes/stats/stats-header.html)

  • Page title and metadata display
  • Generation timestamp information
  • Navigation breadcrumbs

3. Overview Component (_includes/stats/stats-overview.html)

  • High-level metrics cards
  • Total counts for posts, pages, categories, tags
  • Word count statistics and averages

4. Categories Component (_includes/stats/stats-categories.html)

  • Top categories with post counts
  • Dynamic activity level indicators
  • Summary statistics footer

5. Tags Component (_includes/stats/stats-tags.html)

  • Tag usage frequency analysis
  • Interactive tag cloud visualization
  • Usage pattern insights

6. Metrics Component (_includes/stats/stats-metrics.html)

  • Additional quick facts
  • Content distribution information
  • Performance indicators

7. No Data Component (_includes/stats/stats-no-data.html)

  • Graceful error handling
  • User guidance when statistics unavailable
  • Recovery instructions

Data Generation System

Ruby Statistics Generator (_data/generate_statistics.rb)

The heart of the system is a comprehensive Ruby script that:

  • Analyzes Content: Scans all posts, pages, and Jekyll collections
  • Processes Metadata: Extracts categories, tags, and frontmatter data
  • Calculates Metrics: Computes word counts, averages, and distributions
  • Generates YAML: Creates structured data file for Jekyll consumption
  • Handles Errors: Graceful handling of malformed or missing data
# Usage
ruby _data/generate_statistics.rb

# Output: _data/content_statistics.yml

Generated Statistics Include:

  • Overview Metrics: Total posts, pages, categories, tags, words
  • Content Breakdown: Distribution by content type
  • Category Analysis: Usage frequency and activity levels
  • Tag Analysis: Tag cloud data and usage patterns
  • Monthly Distribution: Content creation timeline
  • Word Statistics: Average words per post, total word count

Styling System

Custom CSS (assets/css/stats.css)

Minimal custom styles focusing only on features unavailable in Bootstrap 5:

  • Icon Animations: Smooth rotation and hover effects
  • Shimmer Effects: Loading state animations
  • Tag Cloud Sizing: Dynamic font sizes based on usage
  • Progress Indicators: Enhanced progress bar styling
  • Print Optimization: Clean printing layouts

Bootstrap 5 Integration

Leverages Bootstrap 5 utilities for:

  • Grid System: Responsive layout structure
  • Card Components: Metric containers and visual hierarchy
  • Badge System: Count indicators and labels
  • Typography: Consistent text styling and sizing
  • Spacing: Margin and padding utilities
  • Color System: Theme-consistent color palette

Usage Instructions

Setting Up Statistics

  1. Include the Layout: Create a page with layout: stats
  2. Generate Data: Run the Ruby script to create statistics
  3. Access Dashboard: Visit /about/stats/ or your custom permalink

Example Page Setup

---
title: "Site Statistics"
description: "Comprehensive analytics for site content"
layout: stats
permalink: /stats/
---

Optional content here will appear below the statistics dashboard.

Generating Statistics

# Navigate to your Jekyll site directory
cd /path/to/your/site

# Run the statistics generator
ruby _data/generate_statistics.rb

# Start Jekyll to see updated statistics
bundle exec jekyll serve

Docker Development

# Access Docker container
docker-compose exec jekyll bash

# Generate statistics inside container
ruby _data/generate_statistics.rb

# Exit container (Jekyll auto-reloads)
exit

Customization Options

Activity Level Thresholds

The system automatically calculates activity levels based on your content distribution:

  • Categories: High (≥70% of max), Medium (≥40% of max), Low (remainder)
  • Tags: Frequent (≥60% of max), Moderate (≥20% of max), Occasional (remainder)

Styling Customization

Override default styles by adding custom CSS:

/* Custom activity indicators */
.stats-card .badge.high-activity {
  background-color: var(--bs-success) !important;
}

/* Custom tag cloud sizing */
.tag-cloud .fs-xl {
  font-size: 1.5rem !important;
}

/* Custom animation timing */
.stats-card {
  transition: transform 0.3s ease-in-out;
}

Component Customization

Each component can be customized independently:

<!-- Override in _includes/stats/stats-overview.html -->

Technical Implementation

Data Structure

The generated YAML file follows this structure:

generated_at: '2025-10-10 12:00:00'
overview:
  total_posts: 61
  total_pages: 15
  total_content: 76
  total_categories: 19
  total_tags: 47
  total_words: 43601
  average_words_per_post: 714.8
categories:
  - ["Documentation", 4]
  - ["How-To", 3]
  - ["Development", 3]
tags:
  - ["jekyll", 15]
  - ["docker", 4]
  - ["mermaid", 4]
content_breakdown:
  post: 61
  page: 15
monthly_distribution:
  2025-01: 15
  2025-02: 8

Performance Considerations

  • Data Generation: Run periodically, not on every page load
  • Caching: YAML file acts as cache for computed statistics
  • Lazy Loading: Images and non-critical elements load asynchronously
  • Minimal JavaScript: Only essential interactions included

Browser Compatibility

  • Modern Browsers: Full feature support
  • Legacy Support: Graceful degradation without JavaScript
  • Mobile Optimized: Touch-friendly interface
  • Print Ready: Clean printing layouts

Integration Examples

# _data/navigation.yml
- title: Statistics
  url: /stats/
  icon: bi-bar-chart-line

<!-- _includes/footer.html -->
<a href="/stats/" class="text-muted">
  <i class="bi bi-graph-up"></i> Site Statistics
</a>

Widget Integration

<!-- Show quick stats in sidebar -->

  <div class="card mb-3">
    <div class="card-body text-center">
      <h6 class="card-title">Quick Stats</h6>
      <p class="mb-1">
        <strong>2</strong> Posts
      </p>
      <p class="mb-0">
        <strong>19</strong> Categories
      </p>
      <a href="/stats/" class="btn btn-sm btn-outline-primary mt-2">
        View All Statistics
      </a>
    </div>
  </div>

Best Practices

Content Organization

  • Consistent Categorization: Use standardized category names
  • Strategic Tagging: Apply relevant tags for better insights
  • Regular Updates: Run statistics generation periodically
  • Content Quality: Maintain good writing standards for accurate word counts

Maintenance

  • Automated Generation: Set up scripts to run statistics generation
  • Data Validation: Monitor for outliers or data quality issues
  • Performance Monitoring: Track generation time and file sizes
  • User Feedback: Gather insights on dashboard usefulness

SEO Benefits

  • Content Insights: Identify gaps in content coverage
  • Topic Authority: Understand subject matter focus areas
  • Growth Tracking: Monitor content expansion over time
  • User Engagement: Data-driven content strategy decisions

Troubleshooting

Common Issues

  1. Empty Statistics: Ensure content has proper frontmatter
  2. Generation Errors: Check Ruby script permissions and syntax
  3. Display Issues: Verify Bootstrap 5 is properly loaded
  4. Performance: Consider limiting data processing for large sites

Debug Mode

Enable debug output in the Ruby script:

# Add to generate_statistics.rb
DEBUG = true
puts "Processing: #{file}" if DEBUG

The Statistics Dashboard represents a significant enhancement to the Zer0-Mistakes theme, providing valuable insights into your Jekyll site’s content while maintaining the theme’s focus on simplicity, performance, and user experience.