jekyll-stats 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ebf4d6ad1019af942a6644fe37472e28472ccbbe2ac58f3ba6503bf134f563e0
+  data.tar.gz: e7c6050c13373f795eca54ed88573ee3c46df3a91b6994839e74e4b53dd869fd
+SHA512:
+  metadata.gz: 81fbfb5befa5de983e88c396c97c45f5271e3b42bf17388ea86345e68349f71d8aff0e02f01900827c833b61264620cd15ebcb88b9beadfd01caf239a6825e67
+  data.tar.gz: e833ddc5568285c114f41f75efc29aeb497ff0cfa35388405f80b6b6418b270756f17a8a8be87fe2c5305f7695b0cceb8783a7605e5cf762d8ce0b34a0e6fe92

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-21
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"jekyll-stats" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["andrewnez@gmail.com"](mailto:"andrewnez@gmail.com").

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrew Nesbitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,147 @@
+# jekyll-stats
+
+A Jekyll plugin that adds a `jekyll stats` command to display site statistics.
+
+## Installation
+
+Add to your Jekyll site's Gemfile:
+
+```ruby
+gem "jekyll-stats"
+```
+
+Then run `bundle install`.
+
+## Usage
+
+Run from your Jekyll site directory:
+
+```bash
+# Print stats to terminal
+jekyll stats
+
+# Save stats to _data/stats.json
+jekyll stats --save
+
+# Output raw JSON to stdout
+jekyll stats --json
+
+# Include drafts in calculations
+jekyll stats --drafts
+```
+
+### Terminal Output
+
+```
+Site Statistics
+-----------------------------------
+Posts: 127 (43,521 words, ~3h 38m read time)
+Avg: 343 words | Longest: "My Best Post" (2,847 words)
+First: 2019-03-14 | Last: 2025-12-18 (6.8 years)
+Frequency: 1.6 posts/month
+
+Posts by Year:
+  2025: ████████████ 24
+  2024: ███████████████████ 38
+  2023: ██████████████ 28
+
+Top 10 Tags:
+  ruby (34) | opensource (28) | packages (19)
+
+Categories:
+  code (45) | cars (32)
+-----------------------------------
+```
+
+### JSON Output
+
+The `--save` flag writes `_data/stats.json` with this structure:
+
+```json
+{
+  "generated_at": "2025-12-21T09:30:00Z",
+  "total_posts": 127,
+  "total_words": 43521,
+  "reading_minutes": 218,
+  "average_words": 343,
+  "longest_post": { "title": "My Best Post", "url": "/2024/01/my-best-post", "words": 2847 },
+  "shortest_post": { "title": "Quick Note", "url": "/2024/03/quick-note", "words": 89 },
+  "first_post": { "title": "Hello World", "url": "/2019/03/hello-world", "date": "2019-03-14" },
+  "last_post": { "title": "Recent Post", "url": "/2025/12/recent-post", "date": "2025-12-18" },
+  "years_active": 6.8,
+  "posts_per_month": 1.6,
+  "posts_by_year": [{ "year": 2025, "count": 24 }, { "year": 2024, "count": 38 }],
+  "posts_by_month": [{ "month": "2025-12", "count": 3 }],
+  "posts_by_day_of_week": { "monday": 23, "tuesday": 18, "wednesday": 15, "thursday": 20, "friday": 22, "saturday": 14, "sunday": 15 },
+  "tags": [{ "name": "ruby", "count": 34 }, { "name": "opensource", "count": 28 }],
+  "categories": [{ "name": "code", "count": 45 }, { "name": "cars", "count": 32 }],
+  "drafts_count": 3
+}
+```
+
+## Building a Stats Page
+
+After running `jekyll stats --save`, create a stats page using Liquid:
+
+```liquid
+---
+layout: page
+title: Site Statistics
+---
+
+<p>
+  <strong>{{ site.data.stats.total_posts }}</strong> posts,
+  <strong>{{ site.data.stats.total_words | divided_by: 1000 }}k</strong> words,
+  <strong>{{ site.data.stats.reading_minutes | divided_by: 60 }}</strong> hours of reading.
+</p>
+
+<p>
+  Writing since {{ site.data.stats.first_post.date }} ({{ site.data.stats.years_active }} years).
+  Averaging {{ site.data.stats.posts_per_month }} posts per month.
+</p>
+
+<h2>Posts by Year</h2>
+<ul>
+{% for year in site.data.stats.posts_by_year %}
+  <li>{{ year.year }}: {{ year.count }} posts</li>
+{% endfor %}
+</ul>
+
+<h2>Top Tags</h2>
+<ul>
+{% for tag in site.data.stats.tags limit:10 %}
+  <li>{{ tag.name }} ({{ tag.count }})</li>
+{% endfor %}
+</ul>
+
+<h2>Extremes</h2>
+<ul>
+  <li>Longest: <a href="{{ site.data.stats.longest_post.url }}">{{ site.data.stats.longest_post.title }}</a> ({{ site.data.stats.longest_post.words }} words)</li>
+  <li>Shortest: <a href="{{ site.data.stats.shortest_post.url }}">{{ site.data.stats.shortest_post.title }}</a> ({{ site.data.stats.shortest_post.words }} words)</li>
+</ul>
+
+<h2>Day of Week</h2>
+<p>
+  I write most on
+  {% assign max_day = "" %}
+  {% assign max_count = 0 %}
+  {% for day in site.data.stats.posts_by_day_of_week %}
+    {% if day[1] > max_count %}
+      {% assign max_day = day[0] %}
+      {% assign max_count = day[1] %}
+    {% endif %}
+  {% endfor %}
+  {{ max_day | capitalize }}s ({{ max_count }} posts).
+</p>
+```
+
+## Development
+
+```bash
+bin/setup
+rake test
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/jekyll-stats/command.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module JekyllStats
+  class Command < Jekyll::Command
+    class << self
+      def init_with_program(prog)
+        prog.command(:stats) do |c|
+          c.syntax "stats [options]"
+          c.description "Display site statistics"
+          c.option "save", "--save", "Save stats to _data/stats.json"
+          c.option "json", "--json", "Output raw JSON to stdout"
+          c.option "drafts", "-D", "--drafts", "Include drafts in calculations"
+          c.option "config", "--config CONFIG_FILE[,CONFIG_FILE2,...]", Array, "Custom configuration file"
+          c.option "source", "-s", "--source SOURCE", "Custom source directory"
+          c.option "destination", "-d", "--destination DESTINATION", "Custom destination directory"
+
+          c.action do |_args, options|
+            process(options)
+          end
+        end
+      end
+
+      def process(options)
+        options = configuration_from_options(options)
+        site = Jekyll::Site.new(options)
+
+        Jekyll.logger.info "Loading site..."
+        site.reset
+        site.read
+
+        calculator = StatsCalculator.new(site, include_drafts: options["drafts"])
+        stats = calculator.calculate
+
+        if options["json"]
+          puts JSON.pretty_generate(stats)
+        else
+          formatter = Formatter.new(stats)
+          puts formatter.to_terminal
+
+          if options["save"]
+            save_stats(site, stats)
+          end
+        end
+      end
+
+      def save_stats(site, stats)
+        data_dir = File.join(site.source, "_data")
+        FileUtils.mkdir_p(data_dir)
+
+        path = File.join(data_dir, "stats.json")
+        File.write(path, JSON.pretty_generate(stats))
+        Jekyll.logger.info "Stats saved to #{path}"
+      end
+    end
+  end
+end

data/lib/jekyll-stats/formatter.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module JekyllStats
+  class Formatter
+    attr_reader :stats
+
+    def initialize(stats)
+      @stats = stats
+    end
+
+    def to_terminal
+      return "No posts found." if stats[:total_posts].zero?
+
+      lines = []
+      lines << ""
+      lines << "\u{1F4CA} Site Statistics"
+      lines << "\u2500" * 35
+
+      lines << post_summary
+      lines << averages_line
+      lines << date_range_line
+      lines << frequency_line
+
+      lines << ""
+      lines << posts_by_year_chart
+
+      if stats[:tags].any?
+        lines << ""
+        lines << top_tags
+      end
+
+      if stats[:categories].any?
+        lines << ""
+        lines << categories_line
+      end
+
+      if stats[:drafts_count].positive?
+        lines << ""
+        lines << "Drafts: #{stats[:drafts_count]}"
+      end
+
+      lines << "\u2500" * 35
+      lines << ""
+
+      lines.join("\n")
+    end
+
+    def post_summary
+      total = stats[:total_posts]
+      words = format_number(stats[:total_words])
+      time = format_reading_time(stats[:reading_minutes])
+      "Posts: #{total} (#{words} words, ~#{time} read time)"
+    end
+
+    def averages_line
+      avg = stats[:average_words]
+      longest = stats[:longest_post]
+      "Avg: #{avg} words | Longest: \"#{truncate(longest[:title], 30)}\" (#{format_number(longest[:words])} words)"
+    end
+
+    def date_range_line
+      first = stats[:first_post][:date]
+      last = stats[:last_post][:date]
+      years = stats[:years_active]
+      "First: #{first} | Last: #{last} (#{years} years)"
+    end
+
+    def frequency_line
+      "Frequency: #{stats[:posts_per_month]} posts/month"
+    end
+
+    def posts_by_year_chart
+      years = stats[:posts_by_year]
+      return "" if years.empty?
+
+      max_count = years.map { |y| y[:count] }.max
+      bar_width = 20
+
+      lines = ["Posts by Year:"]
+      years.first(10).each do |year_data|
+        year = year_data[:year]
+        count = year_data[:count]
+        bar_length = ((count.to_f / max_count) * bar_width).round
+        bar = "\u2588" * bar_length
+        lines << "  #{year}: #{bar} #{count}"
+      end
+      lines.join("\n")
+    end
+
+    def top_tags
+      tags = stats[:tags].first(10)
+      tag_strs = tags.map { |t| "#{t[:name]} (#{t[:count]})" }
+      "Top #{[10, stats[:tags].size].min} Tags:\n  #{tag_strs.join(" | ")}"
+    end
+
+    def categories_line
+      cats = stats[:categories]
+      cat_strs = cats.map { |c| "#{c[:name]} (#{c[:count]})" }
+      "Categories:\n  #{cat_strs.join(" | ")}"
+    end
+
+    def format_number(n)
+      n.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+    end
+
+    def format_reading_time(minutes)
+      if minutes >= 60
+        hours = minutes / 60
+        mins = minutes % 60
+        "#{hours}h #{mins}m"
+      else
+        "#{minutes}m"
+      end
+    end
+
+    def truncate(str, length)
+      return str if str.length <= length
+
+      "#{str[0, length]}..."
+    end
+  end
+end

data/lib/jekyll-stats/stats_calculator.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module JekyllStats
+  class StatsCalculator
+    WORDS_PER_MINUTE = 200
+
+    attr_reader :site, :include_drafts
+
+    def initialize(site, include_drafts: false)
+      @site = site
+      @include_drafts = include_drafts
+    end
+
+    def calculate
+      posts = collect_posts
+      return empty_stats if posts.empty?
+
+      word_counts = posts.map { |p| [p, word_count(p)] }
+      sorted_by_words = word_counts.sort_by { |_, count| -count }
+      sorted_by_date = posts.sort_by { |p| p.date }
+
+      total_words = word_counts.sum { |_, count| count }
+      dates = sorted_by_date.map(&:date)
+
+      {
+        generated_at: Time.now.utc.iso8601,
+        total_posts: posts.size,
+        total_words: total_words,
+        reading_minutes: (total_words / WORDS_PER_MINUTE.to_f).ceil,
+        average_words: (total_words / posts.size.to_f).round,
+        longest_post: post_info(sorted_by_words.first[0], sorted_by_words.first[1]),
+        shortest_post: post_info(sorted_by_words.last[0], sorted_by_words.last[1]),
+        first_post: post_info_with_date(sorted_by_date.first),
+        last_post: post_info_with_date(sorted_by_date.last),
+        years_active: years_active(dates.first, dates.last),
+        posts_per_month: posts_per_month(posts.size, dates.first, dates.last),
+        posts_by_year: posts_by_year(posts),
+        posts_by_month: posts_by_month(posts),
+        posts_by_day_of_week: posts_by_day_of_week(posts),
+        tags: tag_counts(posts),
+        categories: category_counts(posts),
+        drafts_count: drafts_count
+      }
+    end
+
+    def collect_posts
+      posts = site.posts.docs.dup
+      posts += site.drafts if include_drafts && site.respond_to?(:drafts)
+      posts
+    end
+
+    def word_count(post)
+      content = post.content.to_s
+      text = content.gsub(/<[^>]*>/, " ")
+      text = text.gsub(/```[\s\S]*?```/, " ")
+      text = text.gsub(/`[^`]*`/, " ")
+      text = text.gsub(/\[([^\]]*)\]\([^)]*\)/, '\1')
+      text = text.gsub(/[#*_~`]/, "")
+      text.split(/\s+/).count { |w| w.match?(/\w/) }
+    end
+
+    def post_info(post, words)
+      {
+        title: post.data["title"] || "(untitled)",
+        url: post.url,
+        words: words
+      }
+    end
+
+    def post_info_with_date(post)
+      {
+        title: post.data["title"] || "(untitled)",
+        url: post.url,
+        date: post.date.strftime("%Y-%m-%d")
+      }
+    end
+
+    def years_active(first_date, last_date)
+      seconds = (last_date - first_date).to_f
+      days = seconds / 86400.0
+      (days / 365.25).round(1)
+    end
+
+    def posts_per_month(count, first_date, last_date)
+      months = ((last_date.year - first_date.year) * 12) + (last_date.month - first_date.month) + 1
+      (count / months.to_f).round(1)
+    end
+
+    def posts_by_year(posts)
+      counts = posts.group_by { |p| p.date.year }
+                    .transform_values(&:size)
+                    .sort_by { |year, _| -year }
+      counts.map { |year, count| { year: year, count: count } }
+    end
+
+    def posts_by_month(posts)
+      counts = posts.group_by { |p| p.date.strftime("%Y-%m") }
+                    .transform_values(&:size)
+                    .sort_by { |month, _| month }
+                    .reverse
+      counts.map { |month, count| { month: month, count: count } }
+    end
+
+    def posts_by_day_of_week(posts)
+      days = %w[sunday monday tuesday wednesday thursday friday saturday]
+      counts = Hash.new(0)
+      posts.each { |p| counts[days[p.date.wday]] += 1 }
+      days.each_with_object({}) { |day, h| h[day] = counts[day] }
+    end
+
+    def tag_counts(posts)
+      counts = Hash.new(0)
+      posts.each do |post|
+        tags = post.data["tags"] || []
+        tags.each { |tag| counts[tag] += 1 }
+      end
+      counts.sort_by { |_, count| -count }
+            .map { |name, count| { name: name, count: count } }
+    end
+
+    def category_counts(posts)
+      counts = Hash.new(0)
+      posts.each do |post|
+        categories = post.data["categories"] || []
+        categories.each { |cat| counts[cat] += 1 }
+      end
+      counts.sort_by { |_, count| -count }
+            .map { |name, count| { name: name, count: count } }
+    end
+
+    def drafts_count
+      return 0 unless site.respond_to?(:drafts) && site.drafts
+
+      site.drafts.size
+    end
+
+    def empty_stats
+      {
+        generated_at: Time.now.utc.iso8601,
+        total_posts: 0,
+        total_words: 0,
+        reading_minutes: 0,
+        average_words: 0,
+        longest_post: nil,
+        shortest_post: nil,
+        first_post: nil,
+        last_post: nil,
+        years_active: 0,
+        posts_per_month: 0,
+        posts_by_year: [],
+        posts_by_month: [],
+        posts_by_day_of_week: %w[sunday monday tuesday wednesday thursday friday saturday].each_with_object({}) { |d, h| h[d] = 0 },
+        tags: [],
+        categories: [],
+        drafts_count: 0
+      }
+    end
+  end
+end

data/lib/jekyll-stats/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JekyllStats
+  VERSION = "0.1.0"
+end

data/lib/jekyll-stats.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require_relative "jekyll-stats/version"
+require_relative "jekyll-stats/stats_calculator"
+require_relative "jekyll-stats/formatter"
+require_relative "jekyll-stats/command"

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-stats
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrew Nesbitt
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: Adds a 'jekyll stats' command that computes and displays site statistics
+  including post counts, word counts, reading times, tag/category distributions, and
+  posting frequency.
+email:
+- andrewnez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/jekyll-stats.rb
+- lib/jekyll-stats/command.rb
+- lib/jekyll-stats/formatter.rb
+- lib/jekyll-stats/stats_calculator.rb
+- lib/jekyll-stats/version.rb
+homepage: https://github.com/andrew/jekyll-stats
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/andrew/jekyll-stats
+  source_code_uri: https://github.com/andrew/jekyll-stats
+  changelog_uri: https://github.com/andrew/jekyll-stats/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.1
+specification_version: 4
+summary: Jekyll plugin that generates site statistics
+test_files: []