jekyll-stats 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebf4d6ad1019af942a6644fe37472e28472ccbbe2ac58f3ba6503bf134f563e0
-  data.tar.gz: e7c6050c13373f795eca54ed88573ee3c46df3a91b6994839e74e4b53dd869fd
+  metadata.gz: 3465b65818c34b7a72b5b76d9bb242a37487837e5639927ae65c7d9a00b9ac62
+  data.tar.gz: 9e408de4fcfb55f1581a2b1905018852095cd4ae5c9a4a2f7592e252e24e42b0
 SHA512:
-  metadata.gz: 81fbfb5befa5de983e88c396c97c45f5271e3b42bf17388ea86345e68349f71d8aff0e02f01900827c833b61264620cd15ebcb88b9beadfd01caf239a6825e67
-  data.tar.gz: e833ddc5568285c114f41f75efc29aeb497ff0cfa35388405f80b6b6418b270756f17a8a8be87fe2c5305f7695b0cceb8783a7605e5cf762d8ce0b34a0e6fe92
+  metadata.gz: bd03f85ad69f529b003a211a7004acdf0a30851f0a2084abab6f3f142a511a620d7c3d4f755f4dcab6abc2286c55bb5f25c7bec610ccf565e0f012e975ba21d7
+  data.tar.gz: d42e6b8897070b6529b1cc32f7e6e52c11563e2890bcfdd5c03f4a2237216cb2afb80c62d2ec94489fe6433ffb3706e954d308e31c72a1b4f67fa7a486716ab1

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-30
+
+- Add `internal_links` to stats: posts ranked by inbound links from other posts
+- Source posts can be excluded by tag via `jekyll-stats.link_source_exclude_tags` in `_config.yml`
+- `--json` no longer prints "Loading site..." to stdout, so output pipes cleanly to `jq`
+
+## [0.2.0] - 2026-01-03
+
+- Add `--tags` / `-t` option to filter stats by tags
+
 ## [0.1.0] - 2025-12-21
 
 - Initial release

data/README.md

@@ -2,6 +2,8 @@
 
 A Jekyll plugin that adds a `jekyll stats` command to display site statistics.
 
+[rubygems.org/gems/jekyll-stats](https://rubygems.org/gems/jekyll-stats)
+
 ## Installation
 
 Add to your Jekyll site's Gemfile:
@@ -28,6 +30,10 @@ jekyll stats --json
 
 # Include drafts in calculations
 jekyll stats --drafts
+
+# Filter by tags (comma-separated, matches posts with ANY of the tags)
+jekyll stats --tags ruby
+jekyll stats -t ruby,rails
 ```
 
 ### Terminal Output
@@ -75,10 +81,27 @@ The `--save` flag writes `_data/stats.json` with this structure:
   "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 }],
+  "internal_links": [
+    { "url": "/2024/01/foo", "title": "Foo", "inbound_count": 7, "inbound_from": ["/2024/03/bar", "/2024/06/baz"] }
+  ],
   "drafts_count": 3
 }
 ```
 
+### Internal links
+
+`internal_links` lists posts ranked by how many other posts link to them. It matches markdown and `<a href>` links that point at another post's URL, either as a root-relative path or an absolute URL under your site's `url:`. Self-links and duplicate links from the same source post are ignored.
+
+To stop link-list style posts (year in review, roundups) inflating the counts, exclude them as sources by tag in `_config.yml`:
+
+```yaml
+jekyll-stats:
+  link_source_exclude_tags:
+    - roundup
+```
+
+Excluded posts still appear as targets; they just don't contribute outbound links.
+
 ## Building a Stats Page
 
 After running `jekyll stats --save`, create a stats page using Liquid:
@@ -89,50 +112,101 @@ 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>{{ site.data.stats.total_posts }} posts, {{ site.data.stats.total_words }} words, ~{{ site.data.stats.reading_minutes }} minutes reading time.</p>
+
+<p>Average {{ site.data.stats.average_words }} words per post. Longest: <a href="{{ site.data.stats.longest_post.url }}">{{ site.data.stats.longest_post.title }}</a> ({{ site.data.stats.longest_post.words }} words).</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>
+<p>First post: {{ site.data.stats.first_post.date }} | Last post: {{ site.data.stats.last_post.date }} | {{ site.data.stats.years_active }} years active.</p>
 
 <h2>Posts by Year</h2>
-<ul>
+<table>
+  <thead>
+    <tr>
+      <th style="text-align: left">Year</th>
+      <th style="text-align: right">Posts</th>
+    </tr>
+  </thead>
+  <tbody>
 {% for year in site.data.stats.posts_by_year %}
-  <li>{{ year.year }}: {{ year.count }} posts</li>
+    <tr>
+      <td>{{ year.year }}</td>
+      <td style="text-align: right">{{ year.count }}</td>
+    </tr>
 {% endfor %}
-</ul>
+  </tbody>
+</table>
 
 <h2>Top Tags</h2>
-<ul>
+<table>
+  <thead>
+    <tr>
+      <th style="text-align: left">Tag</th>
+      <th style="text-align: right">Posts</th>
+    </tr>
+  </thead>
+  <tbody>
 {% for tag in site.data.stats.tags limit:10 %}
-  <li>{{ tag.name }} ({{ tag.count }})</li>
+    <tr>
+      <td>{{ tag.name }}</td>
+      <td style="text-align: right">{{ tag.count }}</td>
+    </tr>
 {% 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>
+  </tbody>
+</table>
+
+<p><small>Generated {{ site.data.stats.generated_at | date: "%b %d, %Y" }}</small></p>
+```
+
+## Automating Stats Updates
+
+You can regenerate stats automatically before each build.
+
+### Rake Task
+
+```ruby
+# Rakefile
+task :build do
+  sh "jekyll stats --save"
+  sh "jekyll build"
+end
+```
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/deploy.yml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Generate stats
+        run: bundle exec jekyll stats --save
+
+      - name: Commit stats
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add _data/stats.json
+          git diff --staged --quiet || git commit -m "Update site stats"
+          git push
+
+      - name: Build site
+        run: bundle exec jekyll build
+```
+
+### Git Pre-commit Hook
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit
+bundle exec jekyll stats --save
+git add _data/stats.json
 ```
 
 ## Development

data/lib/jekyll-stats/command.rb

@@ -13,6 +13,7 @@ module JekyllStats
           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 "tags", "-t", "--tags TAGS", Array, "Filter stats by tags (comma-separated)"
           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"
@@ -24,6 +25,7 @@ module JekyllStats
       end
 
       def process(options)
+        Jekyll.logger.log_level = :error if options["json"]
         options = configuration_from_options(options)
         site = Jekyll::Site.new(options)
 
@@ -31,7 +33,7 @@ module JekyllStats
         site.reset
         site.read
 
-        calculator = StatsCalculator.new(site, include_drafts: options["drafts"])
+        calculator = StatsCalculator.new(site, include_drafts: options["drafts"], filter_tags: options["tags"])
         stats = calculator.calculate
 
         if options["json"]

data/lib/jekyll-stats/formatter.rb

@@ -34,6 +34,11 @@ module JekyllStats
         lines << categories_line
       end
 
+      if stats[:internal_links].any?
+        lines << ""
+        lines << most_linked_posts
+      end
+
       if stats[:drafts_count].positive?
         lines << ""
         lines << "Drafts: #{stats[:drafts_count]}"
@@ -99,6 +104,15 @@ module JekyllStats
       "Categories:\n  #{cat_strs.join(" | ")}"
     end
 
+    def most_linked_posts
+      links = stats[:internal_links].first(5)
+      lines = ["Most Linked Posts:"]
+      links.each do |l|
+        lines << "  #{l[:inbound_count].to_s.rjust(2)}  #{truncate(l[:title], 50)}"
+      end
+      lines.join("\n")
+    end
+
     def format_number(n)
       n.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
     end

data/lib/jekyll-stats/stats_calculator.rb

@@ -4,11 +4,12 @@ module JekyllStats
   class StatsCalculator
     WORDS_PER_MINUTE = 200
 
-    attr_reader :site, :include_drafts
+    attr_reader :site, :include_drafts, :filter_tags
 
-    def initialize(site, include_drafts: false)
+    def initialize(site, include_drafts: false, filter_tags: nil)
       @site = site
       @include_drafts = include_drafts
+      @filter_tags = normalize_filter_tags(filter_tags)
     end
 
     def calculate
@@ -39,6 +40,7 @@ module JekyllStats
         posts_by_day_of_week: posts_by_day_of_week(posts),
         tags: tag_counts(posts),
         categories: category_counts(posts),
+        internal_links: internal_links(posts),
         drafts_count: drafts_count
       }
     end
@@ -46,9 +48,23 @@ module JekyllStats
     def collect_posts
       posts = site.posts.docs.dup
       posts += site.drafts if include_drafts && site.respond_to?(:drafts)
+      posts = filter_posts_by_tags(posts) if filter_tags
       posts
     end
 
+    def filter_posts_by_tags(posts)
+      posts.select do |post|
+        post_tags = (post.data["tags"] || []).map { |t| normalize_tag(t) }
+        (filter_tags & post_tags).any?
+      end
+    end
+
+    def normalize_filter_tags(tags)
+      return nil if tags.nil? || tags.empty?
+
+      tags.map { |t| normalize_tag(t) }
+    end
+
     def word_count(post)
       content = post.content.to_s
       text = content.gsub(/<[^>]*>/, " ")
@@ -112,22 +128,62 @@ module JekyllStats
       counts = Hash.new(0)
       posts.each do |post|
         tags = post.data["tags"] || []
-        tags.each { |tag| counts[tag] += 1 }
+        tags.each { |tag| counts[normalize_tag(tag)] += 1 }
       end
       counts.sort_by { |_, count| -count }
             .map { |name, count| { name: name, count: count } }
     end
 
+    def normalize_tag(tag)
+      tag.to_s.strip.gsub(/[,;:]+\z/, "").strip
+    end
+
     def category_counts(posts)
       counts = Hash.new(0)
       posts.each do |post|
         categories = post.data["categories"] || []
-        categories.each { |cat| counts[cat] += 1 }
+        categories.each { |cat| counts[normalize_tag(cat)] += 1 }
       end
       counts.sort_by { |_, count| -count }
             .map { |name, count| { name: name, count: count } }
     end
 
+    def internal_links(posts)
+      by_url = posts.each_with_object({}) { |p, h| h[normalize_url(p.url)] = p }
+      exclude = Array(site.config.dig("jekyll-stats", "link_source_exclude_tags")).map { |t| normalize_tag(t) }
+      site_url = site.config["url"].to_s
+
+      inbound = Hash.new { |h, k| h[k] = [] }
+      posts.each do |post|
+        post_tags = (post.data["tags"] || []).map { |t| normalize_tag(t) }
+        next if exclude.any? && (exclude & post_tags).any?
+
+        post.content.to_s.scan(%r{(?:\]\(|<a\s[^>]*href=["'])([^"'\s)]+)}i).flatten.each do |href|
+          href = href.delete_prefix(site_url) unless site_url.empty?
+          next unless href.start_with?("/")
+
+          target = by_url[normalize_url(href)]
+          next unless target
+          next if target == post
+
+          inbound[target] << post
+        end
+      end
+
+      inbound.map { |target, sources|
+        {
+          url: target.url,
+          title: target.data["title"] || "(untitled)",
+          inbound_count: sources.uniq.size,
+          inbound_from: sources.uniq.map(&:url).sort
+        }
+      }.sort_by { |r| [-r[:inbound_count], r[:url]] }
+    end
+
+    def normalize_url(url)
+      url.sub(/[#?].*\z/, "").sub(%r{/index\.html\z}, "").chomp(".html").chomp("/")
+    end
+
     def drafts_count
       return 0 unless site.respond_to?(:drafts) && site.drafts
 
@@ -152,6 +208,7 @@ module JekyllStats
         posts_by_day_of_week: %w[sunday monday tuesday wednesday thursday friday saturday].each_with_object({}) { |d, h| h[d] = 0 },
         tags: [],
         categories: [],
+        internal_links: [],
         drafts_count: 0
       }
     end

data/lib/jekyll-stats/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-stats
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Andrew Nesbitt
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '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.
@@ -63,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.1
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Jekyll plugin that generates site statistics
 test_files: []