lifer 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '008dbf536d2aa375839023322316ccc00216ea3d4c8eef88792e755f1f95d2ff'
-  data.tar.gz: 7fae8aee316e75f8f58b817041d94afead61361a110feaa8e15c1841ea97f26d
+  metadata.gz: a9302b5310be7c9e07cf71edea4b464c6be7251ccf8753f508b308b51879bb8f
+  data.tar.gz: 82a9a1cf45a1a4e33c7a070527b3641d003af94c5b59089ec92194f288fb59fc
 SHA512:
-  metadata.gz: 9b40732cb604bc0661bee53c3edf621d79c22822bb1fc7b8314e580eca9e2eafb09c04b842441812bc387942952f39c4adaf0068e66688a894f060b88a8ba8e8
-  data.tar.gz: f5dbd68e3d6b6267a8dc5c887220a37e71d851f40926b85a762b3c9bfe532f6cf9f9f7e6ac5f3389889be0ae9bc3cdc1b70b5efa4182d1cbc647d1a786779ede
+  metadata.gz: 29c29c7d458205032517bd098e9e89a98ea0a7e3b5585eb14e2b46aa881779bcbac218ab2671054db5f7c408682e466cbeadc794a658b93f7d5f8fe91c42fb89
+  data.tar.gz: 4915942529c379b870f265699efce4493a0d532a0b686bc822850aa822450d811b964e2b9e20551931b92e118d2448308bd0ff1a586866901b585d8ae4fadbb0

data/CHANGELOG.md

@@ -1,4 +1,21 @@
 ## Next
+
+## v0.6.0
+
+This release contains improvements to RSS feed generation:
+
+- Additonal settings per RSS feed (maximum feed item count and configurable
+  managing editor metadata).
+- No more invalid `<managingEditor>` values. A default managing editor email is
+  now prefixed to the default collection author name for [W3C validated
+  feeds][w3c-feed-checker].
+
+[w3c-feed-checker]: https://validator.w3.org/feed/check.cgi
+
+## v0.5.1
+
+Resolved warnings output by `gem build`.
+
 ## v0.5.0
 
 This release refactors all of our builders to use parallelization, meaning that

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lifer (0.5.0)
+    lifer (0.6.0)
       i18n (< 2)
       kramdown (~> 2.4)
       liquid (~> 5.6, < 6)
@@ -9,7 +9,7 @@ PATH
       parallel (~> 1.26, < 2)
       puma (< 7)
       rack (< 4)
-      rss
+      rss (< 1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -98,6 +98,8 @@ Then use Bump to perform release chores and create a version tag:
 
     $ bundle exec bump <minor|patch> --tag --changelog --edit-changelog
     $ git push origin <new_version>
+    $ gem build
+    $ gem push lifer-<new_version_without_the_v_prefix>.gem
 
 (Where `new_version` is the version you intend to release. For example:
 `v1.2.3`.)

data/lib/lifer/builder/rss.rb

@@ -1,14 +1,60 @@
 require "fileutils"
 require "rss"
 
-# Builds a simple RSS 2.0[1] feed using the Ruby standard library's RSS
+# Builds a simple, UTF-8, RSS 2.0[1] feed using the Ruby standard library's RSS
 # features.
 #
+# The features of the generated feed attempt to follow the recommendations for
+# RSS feeds specified by RSS Board[2].
+#
+# The RSS builder can be configured in a number of ways:
+#
+# 1. Boolean
+#
+#    Simply set `rss: true` or `rss: false` to enable or disable a feed for a
+#    collection. If `true`, an RSS feed will be built to `name-of-collection.xml`
+#
+# 2. Simple
+#
+#    Simply set `rss: name-of-output-file.xml` to specify the name of the
+#    output XML file.
+#
+# 3. Fine-grained
+#
+#    Provide an object under `rss:` for more fine-grained control over
+#    configuration. The following sub-settings are supported:
+#
+#    - `count:` - The limit of RSS feed items that should be included in the
+#      output document. Leave unset or set to `0` to include all entries.
+#    - `managing_editor:` - the contents of the `<managingEditor>` node of the
+#      RSS document. When unset, Lifer builds a valid `<managingEditor>` value
+#      using the collection or root `author` value and a null email address to
+#      ensure that RSS feed validators are satisfied.
+#    - `url:` -  the path to the filename of the output XML file.
+#
 # [1]: https://www.rssboard.org/rss-specification
+# [2]: https://www.rssboard.org/rss-profile
 #
 class Lifer::Builder::RSS < Lifer::Builder
+  # Because Lifer has no reason to have record of anyone's email address, we
+  # provide a non-email address so a <managingEditor> can be set and validated by
+  # RSS validators.
+  #
+  # Note that `.invalid` is a special-use TLD[1] that helps us indicate that the
+  # email address is definitely not real.
+  #
+  # [1]: https://datatracker.ietf.org/doc/html/rfc6761
+  #
+  DEFAULT_MANAGING_EDITOR_EMAIL = "editor@null.invalid"
+
   self.name = :rss
-  self.settings = [:rss]
+  self.settings = [
+    rss: [
+      :count,
+      :managing_editor,
+      :url
+    ]
+  ]
 
   class << self
     # Traverses and renders an RSS feed for each feedable collection in the
@@ -35,8 +81,10 @@ class Lifer::Builder::RSS < Lifer::Builder
       File.open filename, "w" do |file|
         file.puts(
           rss_feed_for(collection) do |current_feed|
+            max_index = max_feed_items(collection) - 1
+
             collection.entries
-              .select { |entry| entry.feedable? }
+              .select { |entry| entry.feedable? }[0..max_index]
               .each { |entry| rss_entry current_feed, entry }
           end.to_feed
         )
@@ -54,17 +102,75 @@ class Lifer::Builder::RSS < Lifer::Builder
     @root = root
   end
 
+  # According to the RSS Board, the recommended format for the
+  # `<managingEditor>` feed data is
+  #
+  #     editor@example.com (Editor Name)
+  #
+  # Unfortunately, Lifer has no reason to have record of the editor's email
+  # address except for in RSS feeds, so if an `rss.managing_editor` is not
+  # configured we'll do our best to at provide information managing editor's
+  # that RSS feed validators are satisified with using other site configuration
+  # containing an author's name. Example output:
+  #
+  #     editor@null.invalid (Configured Author Name)
+  #
+  # @param collection [Lifer::Collection]
+  # @return [String] The managing editor string for a `<managingEditor>` RSS
+  #   feed field.
+  def managing_editor(collection)
+    editor = collection.setting(:rss, :managing_editor)
+
+    return editor if editor
+
+    "%s (%s)" % [
+      DEFAULT_MANAGING_EDITOR_EMAIL,
+      Lifer.setting(:author, collection: collection)
+    ]
+  end
+
+  # The amount of feed items to output to the RSS file. If set to 0, there is no
+  # max limit of feed items.
+  #
+  # @param collection [Lifer::Collection]
+  # @return [Integer]
+  def max_feed_items(collection) = Lifer.setting(:rss, :count, collection:) || 0
+
   def output_filename(collection)
-    strict_mode = !collection.root?
+    strict = !collection.root?
 
-    case collection.setting(:rss, strict: strict_mode)
+    case collection.setting(:rss, strict:)
     when FalseClass, NilClass then nil
-    when TrueClass then File.join(Dir.pwd, "#{collection.name}.xml")
-    else
-      File.join Dir.pwd, collection.setting(:rss, strict: strict_mode)
+    when TrueClass
+      File.join Dir.pwd, "#{collection.name}.xml"
+    when Hash
+      File.join Dir.pwd, collection.setting(:rss, :url, strict:)
+    when String
+      File.join Dir.pwd, collection.setting(:rss, strict:)
     end
   end
 
+  # FIXME: Using the W3C feed validation checker[1], I found that RSS feed items
+  #   generated by Lifer are missing some recommended functionality. Reports
+  #
+  #   > This feed is valid, but interoperability with the widest range of feed
+  #   > readers could be improved by implementing the following recommendations.
+  #   >
+  #   > An item should not include both pubDate and dc:date
+  #   > (https://validator.w3.org/feed/docs/warning/DuplicateItemSemantics.html)
+  #   >
+  #   > item should contain a guid element
+  #   > (https://validator.w3.org/feed/docs/warning/MissingGuid.html)
+  #   >
+  #   > content:encoded should not contain relative URL references
+  #   > (https://validator.w3.org/feed/docs/warning/ContainsRelRef.html)
+  #
+  #   Regarding the `<content:encoded>` field... this seems to be more closely
+  #   related to our Markdown parser implementation than the RSS feed generation
+  #   itself.
+  #
+  #   [1]: https://validator.w3.org/feed/check.cgi
+  #
   def rss_entry(rss_feed, lifer_entry)
     rss_feed.maker.items.new_item do |rss_feed_item|
       if (authors = lifer_entry.authors).any?
@@ -79,6 +185,14 @@ class Lifer::Builder::RSS < Lifer::Builder
     end
   end
 
+  # FIXME: Using the W3C feed validation checker[1], I found that RSS feeds
+  #   generated by Lifer are missing some recommended functionality. Reports:
+  #
+  #   > Missing atom:link with rel="self"
+  #   > (https://validator.w3.org/feed/docs/warning/MissingAtomSelfLink.html)
+  #
+  #   [1]: https://validator.w3.org/feed/check.cgi
+  #
   def rss_feed_for(collection, &block)
     feed_object = nil
 
@@ -96,11 +210,8 @@ class Lifer::Builder::RSS < Lifer::Builder
         Lifer.setting(:rss, collection: collection)
       ]
 
-      feed.channel.managingEditor =
-        Lifer.setting(:site_default_author, collection: collection)
-
+      feed.channel.managingEditor = managing_editor(collection)
       feed.channel.title = Lifer.setting(:title, collection: collection)
-
       feed.channel.webMaster =
         Lifer.setting(:site_default_author, collection: collection)
 

data/lib/lifer/config.rb

@@ -118,14 +118,14 @@ class Lifer::Config
     name_in_collection = name.dup.unshift(collection_name) if collection_name
 
     return if strict && collection_name.nil?
-    return settings.dig(*name_in_collection) if (strict && collection_name)
+    return dig_from(settings, *name_in_collection) if (strict && collection_name)
 
     candidates = [
-      settings.dig(*name),
-      default_settings.dig(*name),
-      DEFAULT_IMPLICIT_SETTINGS.dig(*name)
+      dig_from(settings, *name),
+      dig_from(default_settings, *name),
+      dig_from(DEFAULT_IMPLICIT_SETTINGS, *name)
     ]
-    candidates.unshift settings.dig(*name_in_collection) if name_in_collection
+    candidates.unshift dig_from(settings, *name_in_collection) if name_in_collection
 
     candidates.detect &:itself
   end
@@ -173,6 +173,12 @@ class Lifer::Config
       Lifer::Utilities.symbolize_keys(YAML.load_file DEFAULT_CONFIG_FILE).to_h
   end
 
+  def dig_from(hash, *keys)
+    keys.reduce(hash) { |result, key|
+      result.is_a?(Hash) || result.is_a?(Array) ? result[key] : nil
+    }
+  end
+
   def has_collection_settings?(settings_key)
     confirmed_collections = collection_candidates & unregistered_settings.keys
 

data/lib/lifer/entry/markdown.rb

@@ -119,6 +119,11 @@ class Lifer::Entry::Markdown < Lifer::Entry
 
   # The HTML representation of the Markdown entry as parsed by Kramdown.
   #
+  # FIXME: Before converting a Kramdown document to Markdown, we chould
+  #   convert any relative URLs to absolute ones. This makes it more flexible to
+  #   use HTML output where ever we want, especially in RSS feeds where feed
+  #   readers may "wtf" a relative URL.
+  #
   # @return [String] The HTML for the body of the entry.
   def to_html
     Kramdown::Document.new(body).to_html

data/lib/lifer/version.rb

@@ -1,3 +1,3 @@
 module Lifer
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lifer.gemspec

@@ -7,6 +7,7 @@ Gem::Specification.new do |spec|
   spec.version       = Lifer::VERSION
   spec.authors       = ["benjamin wil"]
   spec.email         = ["benjamin@super.gd"]
+  spec.licenses      = ["MIT"]
 
   spec.summary       = "Minimal static weblog generator."
   spec.description   = "Minimal static weblog generator. Good RSS feeds."
@@ -15,8 +16,10 @@ Gem::Specification.new do |spec|
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["homepage_uri"] =
+    "%s/blob/%s/README.md" % [spec.homepage, Lifer::VERSION]
+  spec.metadata["source_code_uri"] =
+    "%s/tree/%s" % [spec.homepage, Lifer::VERSION]
   spec.metadata["changelog_uri"] = "%s/blob/main/CHANGELOG.md" % spec.homepage
 
   # Specify which files should be added to the gem when it is released. The
@@ -40,5 +43,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency "parallel", ["~> 1.26", "< 2"]
   spec.add_dependency "puma", "< 7"
   spec.add_dependency "rack", "< 4"
-  spec.add_dependency "rss"
+  spec.add_dependency "rss", "< 1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lifer
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - benjamin wil
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-16 00:00:00.000000000 Z
+date: 2025-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
@@ -124,16 +124,16 @@ dependencies:
   name: rss
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1'
 description: Minimal static weblog generator. Good RSS feeds.
 email:
 - benjamin@super.gd
@@ -203,11 +203,12 @@ files:
 - lifer.gemspec
 - locales/en.yml
 homepage: https://github.com/benjaminwil/lifer
-licenses: []
+licenses:
+- MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/benjaminwil/lifer
-  source_code_uri: https://github.com/benjaminwil/lifer
+  homepage_uri: https://github.com/benjaminwil/lifer/blob/0.6.0/README.md
+  source_code_uri: https://github.com/benjaminwil/lifer/tree/0.6.0
   changelog_uri: https://github.com/benjaminwil/lifer/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []