lifer 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9ccb1942c2bb2b9cc5dafc28700275358f43579761c8039a621b082445da70d
-  data.tar.gz: 48e0f8e204cc65fae8f1ddec4d10da85b9b7bb0d2f87a875d57896b54e4c02a6
+  metadata.gz: a9302b5310be7c9e07cf71edea4b464c6be7251ccf8753f508b308b51879bb8f
+  data.tar.gz: 82a9a1cf45a1a4e33c7a070527b3641d003af94c5b59089ec92194f288fb59fc
 SHA512:
-  metadata.gz: 21497c604f22994484a1dfe7fe082052aa2cc07b9fe0bd27161046a346eb465caa6afdd2f1620fc1052b6cce19654523bcdf6371f97ca7d0643122f102079b26
-  data.tar.gz: 58f941ae10d2a95157c20c88b4a7c657f3810f783441b09e4093f49008ee267182458387ed6b4e383e383889473d5a6a1fdf5e12d1725dfbb32f1de2e21d2dca
+  metadata.gz: 29c29c7d458205032517bd098e9e89a98ea0a7e3b5585eb14e2b46aa881779bcbac218ab2671054db5f7c408682e466cbeadc794a658b93f7d5f8fe91c42fb89
+  data.tar.gz: 4915942529c379b870f265699efce4493a0d532a0b686bc822850aa822450d811b964e2b9e20551931b92e118d2448308bd0ff1a586866901b585d8ae4fadbb0

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## 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`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lifer (0.5.1)
+    lifer (0.6.0)
       i18n (< 2)
       kramdown (~> 2.4)
       liquid (~> 5.6, < 6)

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.1"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lifer
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  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
@@ -207,8 +207,8 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/benjaminwil/lifer/blob/0.5.1/README.md
-  source_code_uri: https://github.com/benjaminwil/lifer/tree/0.5.1
+  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: []