lifer 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39e8d5c991a955d4c09740207671d49716b6ef42168b250fbe301c6a443785d5
-  data.tar.gz: 73e4ea67bc8e9af6f1503782c53c334c5d59f31a2afd351312eb8365b9b42af7
+  metadata.gz: a2f61316d5e10ff4212470b5539741a4204f35976f97d193ef7aabfd944c62a5
+  data.tar.gz: 03b9aafb098ab04f2aa1306fa34512d9627801d468910fb48cd5e10a736b7e47
 SHA512:
-  metadata.gz: eacb4bd82e882758d88e9ffc0de30de8cb9213f35454856a2bed3f487bb8dc568afdb07ac22d6c269ac1b4c9418a18789dcd124193de009456243a2eeedc6415
-  data.tar.gz: a8dd94d4c24932faae325461a4530c7f931d7ee7315353dc31ca42dac61c325ca91edd5f4f990e0710f4c18d4fbb9b020f51c1f13d8a02012d7c7f4918f5f88e
+  metadata.gz: 5c1f46e3c16622144cc513b3496d4d0bb9f14231d1b92960b63249b3962753355ed92d5a27ed12ad3bd930e0e56ef871b4551bb4d888e11384191f5747580b19
+  data.tar.gz: bcc5771d87e311dfe52d1c2bc79d9386c8f3677b7f3eafb66100815a9d76b2c8e2b5ce60855424d276c1cc8d8fb5e1c42f2298c5d662edf1ee85d03f8ec1a9c8

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## Next
 
+## v0.7.0
+
+This release adds Atom feed support to the RSS builder. In your configuration
+file, you can configure feed formats to `rss` (the default) or `atom` now:
+
+    my_collection:
+      rss:
+        format: atom
+        url: haha.xml
+
 ## v0.6.1
 
 This release just fixes a mistake I made, where I built and pushed a tag from a

data/Gemfile.lock

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

data/lib/lifer/brain.rb

@@ -125,8 +125,7 @@ class Lifer::Brain
   # value. If the in-scope collection does not have a configured setting, this
   # method will return fallback settings (unless `:strict` is `true`).
   #
-  # Example usage:
-  #
+  # @example Usage:
   #     setting(:my, :great, :setting)
   #
   # @overload setting(path, ..., collection: nil, strict: false)
@@ -160,12 +159,6 @@ class Lifer::Brain
     path.start_with?("/") ? path : File.join(root, path)
   end
 
-  # FIXME:
-  # Do collections work with sub-subdirectories? For example, what if the
-  # configured collection maps to a directory:
-  #
-  #     subdirectory_one/sub_subdirectory_one
-  #
   # @return [Set<Lifer::Collection>]
   def generate_collections
     config.collectionables

data/lib/lifer/builder/html/from_liquid/drops/collection_drop.rb

@@ -1,9 +1,9 @@
 module Lifer::Builder::HTML::FromLiquid::Drops
   # This drop allows users to access Lifer collection information from within
-  # Liquid templates. Example:
+  # Liquid templates.
   #
+  # @example Usage
   #     {{ collection.name }}
-  #
   #     {% for entries in collection.entries %}
   #       {{ entry.title }}
   #     {% endfor %}

data/lib/lifer/builder/html/from_liquid/drops/collections_drop.rb

@@ -1,7 +1,8 @@
 module Lifer::Builder::HTML::FromLiquid::Drops
   # This drop allows users to iterate over their Lifer collections in Liquid
-  # templates. Example:
+  # templates.
   #
+  # @example Usage
   #     {% for collection in collections %}
   #       {{ collection.name }}
   #     {% endfor %}
@@ -27,8 +28,9 @@ module Lifer::Builder::HTML::FromLiquid::Drops
     def to_a = @collections
 
     # Dynamically define Liquid accessors based on the Lifer project's
-    # collection names. For example, to get the root collection's name:
+    # collection names.
     #
+    # @example Get the root collection's name.
     #    {{ collections.root.name }}
     #
     # @param arg [String] The name of a collection.

data/lib/lifer/builder/html/from_liquid/drops/entry_drop.rb

@@ -2,8 +2,7 @@ module Lifer::Builder::HTML::FromLiquid::Drops
   # This drop represents a Lifer entry and allows users to access entry
   # metadata and content in Liquid templates.
   #
-  # Example usage:
-  #
+  # @example Usage
   #     <h1>{{ entry.title }}</h1>
   #     <small>Published on <datetime>{{ entry.date }}</datetime></small>
   #

data/lib/lifer/builder/html/from_liquid/drops/frontmatter_drop.rb

@@ -2,8 +2,7 @@ module Lifer::Builder::HTML::FromLiquid::Drops
   # Markdown entries may contain YAML frontmatter. And if they do, we need a way
   # for the Liquid templates to access that data.
   #
-  # Example usage:
-  #
+  # @example Usage
   #     {{ entry.frontmatter.any_available_frontmatter_key }}
   #
   class FrontmatterDrop < Liquid::Drop
@@ -18,8 +17,8 @@ module Lifer::Builder::HTML::FromLiquid::Drops
     def to_s = frontmatter.to_json
 
     # Dynamically define Liquid accessors based on the Lifer settings object.
-    # For example, to get a collections URI strategy:
     #
+    # @example Get a collection's URI strategy.
     #    {{ settings.my_collection.uri_strategy }}
     #
     # @param arg [String] The name of a collection.

data/lib/lifer/builder/html/from_liquid/drops/settings_drop.rb

@@ -2,6 +2,7 @@ module Lifer::Builder::HTML::FromLiquid::Drops
   # This drop allows users to access the current Lifer project settings from
   # Liquid templates. Example:
   #
+  # @example Usage
   #     {{ settings.my_collection.uri_strategy }}
   #
   class SettingsDrop < Liquid::Drop
@@ -15,8 +16,8 @@ module Lifer::Builder::HTML::FromLiquid::Drops
     def to_s = settings.to_json
 
     # Dynamically define Liquid accessors based on the Lifer settings object.
-    # For example, to get a collections URI strategy:
     #
+    # @example Get a collections URI strategy:
     #    {{ settings.my_collection.uri_strategy }}
     #
     # @param arg [String] The name of a collection.

data/lib/lifer/builder/html/from_liquid/filters.rb

@@ -1,8 +1,7 @@
 # This module provides Liquid filters to be used within Liquid templates.
 # In many cases these utilities exist to be pseudo-compatible with Jekyll.
 #
-# For example, a filter (in a Liquid template):
-#
+# @example A filter in a Liquid template.
 #     {{ entry.date | date_to_xmlschema }}
 #
 module Lifer::Builder::HTML::FromLiquid::Filters
@@ -17,10 +16,9 @@ module Lifer::Builder::HTML::FromLiquid::Filters
 
   # Transforms a string to kabab-case.
   #
-  # For example:
+  # @example Result
+  #     handleize("hello_there") #=> "hello-there"
   #
-  #     Before: hello_there
-  #     After: hello-there
   # @param input [String] A string.
   # @return [String] The transformed string.
   def handleize(input) = Util.handleize(input)

data/lib/lifer/builder/html/from_liquid/layout_tag.rb

@@ -11,8 +11,7 @@ class Lifer::Builder::HTML::FromLiquid
   # frontmatter when we didn't need to. Maybe in the long run this was a bad
   # call? I don't know.
   #
-  # Example usage (from a Liquid template):
-  #
+  # @example Usage from a Liquid template.
   #     {% layout "path/to/my_liquid_layout_template" %}
   #
   # (The required `endlayout` tag will be appended to the end of the file

data/lib/lifer/builder/html.rb

@@ -74,7 +74,7 @@ class Lifer::Builder::HTML < Lifer::Builder
   # For the given collection, ensure all required directories and
   # subdirectories exist so the entry output can be safely written to.
   #
-  # @param entry [Lifer::Collection] A collection.
+  # @param collection [Lifer::Collection] A collection.
   # @return [void]
   def generate_output_directories_for(collection)
     directories = collection.entries

data/lib/lifer/builder/rss.rb

@@ -1,6 +1,9 @@
 require "fileutils"
 require "rss"
 
+# FIXME: Can this feed builder just take a type for Atom feeds instead of us
+#  creating a separate builder?
+
 # Builds a simple, UTF-8, RSS 2.0[1] feed using the Ruby standard library's RSS
 # features.
 #
@@ -26,6 +29,8 @@ require "rss"
 #
 #    - `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.
+#    - `format:` - The RSS format to build with. Either `rss` or `atom` are
+#      supported. `rss` is the default format.
 #    - `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
@@ -47,10 +52,27 @@ class Lifer::Builder::RSS < Lifer::Builder
   #
   DEFAULT_MANAGING_EDITOR_EMAIL = "editor@null.invalid"
 
+  # All of the available formats that this builder can build. Where the keys
+  # are formats accepted as input in configuration files and the values are
+  # the formats that the RSS builder will output.
+  #
+  FORMATS = {atom: "atom", rss: "rss2.0"}
+
+  # The default format for this RSS feed builder. Where the key is the format
+  # accepted as input in configuration files and the value is the format that
+  # the RSS builder will output.
+
+  # The name of the format type, as needed by `RSS::Maker`, used by default by
+  # this feed builder.
+  #
+  DEFAULT_MAkER_FORMAT_NAME = FORMATS[:rss]
+
+
   self.name = :rss
   self.settings = [
     rss: [
       :count,
+      :format,
       :managing_editor,
       :url
     ]
@@ -69,6 +91,14 @@ class Lifer::Builder::RSS < Lifer::Builder
     end
   end
 
+  def feed_format(collection)
+    format = Lifer.setting(:rss, :format, collection:)&.to_sym
+
+    return FORMATS[format] if FORMATS.keys.include? format
+
+    DEFAULT_MAkER_FORMAT_NAME
+  end
+
   # Traverses and renders an RSS feed for feedable collection.
   #
   # @return [void]
@@ -150,8 +180,10 @@ class Lifer::Builder::RSS < Lifer::Builder
     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
+  # @fixme Using the W3C feed validation checker[1], I found that RSS and Atom
+  #   feed items generated by Lifer are missing some recommended functionality.
+  #
+  #   RSS reports:
   #
   #   > This feed is valid, but interoperability with the widest range of feed
   #   > readers could be improved by implementing the following recommendations.
@@ -169,6 +201,14 @@ class Lifer::Builder::RSS < Lifer::Builder
   #   related to our Markdown parser implementation than the RSS feed generation
   #   itself.
   #
+  #   Atom reports:
+  #
+  #   > Two or more entries with the same value for <atom:updated>
+  #   > (https://validator.w3.org/feed/docs/warning/DuplicateUpdated.html)
+  #   >
+  #   > Missing <atom:link> with rel="self".
+  #   > (https://validator.w3.org/feed/docs/warning/MissingSelf.html)
+  #
   #   [1]: https://validator.w3.org/feed/check.cgi
   #
   def rss_entry(rss_feed, lifer_entry)
@@ -185,7 +225,7 @@ class Lifer::Builder::RSS < Lifer::Builder
     end
   end
 
-  # FIXME: Using the W3C feed validation checker[1], I found that RSS feeds
+  # @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"
@@ -196,20 +236,34 @@ class Lifer::Builder::RSS < Lifer::Builder
   def rss_feed_for(collection, &block)
     feed_object = nil
 
-    ::RSS::Maker.make "rss2.0" do |feed|
+    ::RSS::Maker.make feed_format(collection) do |feed|
       feed.channel.description =
         Lifer.setting(:description, collection: collection) ||
           Lifer.setting(:site_title, collection: collection)
 
       feed.channel.language = Lifer.setting(:language, collection: collection)
 
-      feed.channel.lastBuildDate = Time.now.to_s
-
-      feed.channel.link = "%s/%s" % [
+      channel_link = "%s/%s" % [
         Lifer.setting(:global, :host),
-        Lifer.setting(:rss, collection: collection)
+        Lifer.setting(:rss, :url, collection:)
       ]
 
+      # The W3C Atom validator claims that the <id> should be a "canonicalized"
+      # URL with a slash at the end.
+      #
+      channel_link = channel_link + "/" unless channel_link.end_with?("/")
+
+      feed.channel.lastBuildDate = Time.now.to_s
+      feed.channel.link = channel_link
+
+      # Additional channel fields for Atom format feeds.
+      #
+      if feed_format(collection) == "atom"
+        feed.channel.author = Lifer.setting(:author, collection: collection)
+        feed.channel.id = channel_link
+        feed.channel.updated = Time.now.to_s
+      end
+
       feed.channel.managingEditor = managing_editor(collection)
       feed.channel.title = Lifer.setting(:title, collection: collection)
       feed.channel.webMaster =

data/lib/lifer/builder.rb

@@ -18,7 +18,8 @@ class Lifer::Builder
     # Every builder class must have execute method. This is the entrypoint for
     # instantiating *and* executing any builder.
     #
-    # @param root [string] An absolute path to the Lifer project root directory.
+    # @param root [string] An absolute path to the Lifer project root
+    #   directory.
     # @return [NotImplementedError] A builder subclass must implement this
     #   method.
     def execute(root:) = (raise NotImplementedError)

data/lib/lifer/config.rb

@@ -33,7 +33,7 @@ class Lifer::Config
   # Provides "implicit settings" that may not be set anywhere but really do
   # require a value.
   #
-  # FIXME: I don't think this really belongs here. But in some cases we need
+  # @fixme I don't think this really belongs here. But in some cases we need
   #   to provide the implicit setting key and a default value when calling the
   #   `#setting` method. It would be nicer if the HTML builder handled this,
   #   somehow.

data/lib/lifer/dev/response.rb

@@ -33,9 +33,8 @@ module Lifer::Dev
       [File.read(path)]
     end
 
-    # FIXME:
-    # It would be very nice to not manually manage this list of content types.
-    # Is there a nice, dependency-free way to do this?
+    # @fixme  It would be very nice to not manually manage this list of
+    #   content types. Is there a nice, dependency-free way to do this?
     #
     def content_type
       case File.extname(path)

data/lib/lifer/dev/server.rb

@@ -71,8 +71,8 @@ module Lifer::Dev
       # @private
       # On reload, we rebuild the Lifer project.
       #
-      # FIXME:
-      # Partial rebuilds would be a nice enhancement for performance reasons.
+      # @fixme Partial rebuilds would be a nice enhancement for performance
+      #   reasons.
       #
       def reload!
         if @changes
@@ -84,7 +84,6 @@ module Lifer::Dev
 
       # @private
       # @return [Lifer::Dev::Router] Our dev server router.
-      #
       def router
         return @router if @router && !test_mode?
 

data/lib/lifer/entry/html.rb

@@ -7,9 +7,9 @@ class Lifer::Entry::HTML < Lifer::Entry
   self.input_extensions = ["html", "html.erb", "html.liquid"]
   self.output_extension = :html
 
-  # FIXME: This could probably get more sophisticated, but at the moment HTML
-  # entries don't have any way to provide metadata about themselves. So let's
-  # just give them a default date to start.
+  # @fixme This could probably get more sophisticated, but at the moment HTML
+  #   entries don't have any way to provide metadata about themselves. So let's
+  #   just give them a default date to start.
   #
   # @return [Time] The publication date of the HTML entry.
   def date = Lifer::Entry::DEFAULT_DATE

data/lib/lifer/entry/markdown.rb

@@ -6,11 +6,11 @@ require_relative "../utilities"
 
 # We should initialize each Markdown file in a Lifer project as a
 # `Lifer::Entry::Markdown` object. This class contains convenience methods for
-# parsing a Markdown file with frontmatter as a weblog post or article. Of course,
-# all frontmatter key-values will be available for users to render as they will in
-# their template files.
+# parsing a Markdown file with frontmatter as a weblog post or article. Of
+# course, all frontmatter key-values will be available for users to render as
+# they will in their template files.
 #
-# FIXME: As we add other types of entries, especially ones that use frontmatter,
+# @fixme As we add other types of entries, especially ones that use frontmatter,
 # it may make sense to pull some of these methods into a separate module.
 #
 class Lifer::Entry::Markdown < Lifer::Entry
@@ -86,15 +86,14 @@ class Lifer::Entry::Markdown < Lifer::Entry
     )
   end
 
-  # FIXME:
-  # This would be easier to test and more appropriate as a module method
-  # takes text and options as arguments.
-  #
   # If given a summary in the frontmatter of the entry, we can use this to
   # provide a summary. Otherwise, we can truncate the first paragraph and use
   # that as a summary, although that is a bit annoying. This is useful for
   # indexes and feeds and so on.
   #
+  # @fixme This would be easier to test and more appropriate as a module method
+  #   takes text and options as arguments.
+  #
   # @return [String] A summary of the entry.
   def summary
     return frontmatter[:summary] if frontmatter[:summary]
@@ -119,9 +118,9 @@ 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
+  # @fixme Before converting a Kramdown document to Markdown, we should 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.

data/lib/lifer/entry/txt.rb

@@ -7,9 +7,9 @@ class Lifer::Entry::TXT < Lifer::Entry
   self.input_extensions = ["txt"]
   self.output_extension = :txt
 
-  # FIXME: This could probably get more sophisticated, but at the moment HTML
-  # entries don't have any way to provide metadata about themselves. So let's
-  # just give them a default date to start.
+  # @fixme This could probably get more sophisticated, but at the moment HTML
+  #   entries don't have any way to provide metadata about themselves. So let's
+  #   just give them a default date to start.
   #
   # @return [Time] The publication date of the HTML entry.
   def date = Lifer::Entry::DEFAULT_DATE
@@ -34,7 +34,7 @@ class Lifer::Entry::TXT < Lifer::Entry
   # While we don't actually output text to HTML, we need to implement this
   # method so that the RSS feed builder can add text files as feed entries.
   #
-  # FIXME: Maybe the `#to_html` methods should be renamed, then?
+  # @fixme Maybe the `#to_html` methods should be renamed, then?
   #
   # @return [String] The output HTML (not actually HTML).
   def to_html = full_text

data/lib/lifer/entry.rb

@@ -8,7 +8,7 @@ require "digest/sha1"
 # should implement. It also provides the entry generator for *all* entry
 # subclasses.
 #
-# FIXME: Markdown entries are able to provide metadata via frontmatter, but
+# @fixme Markdown entries are able to provide metadata via frontmatter, but
 #   other entry types do not currently support frontmatter. Should they? Or is
 #   there some nicer way to provide entry metadata for non-Markdown files in
 #   2024?

data/lib/lifer/selection.rb

@@ -48,13 +48,13 @@ class Lifer::Selection < Lifer::Collection
     raise NotImplementedError, I18n.t("selection.entries_not_implemented")
   end
 
-  # FIXME:
-  # Getting selection settings may actually need to be different than getting
-  # collection settings. But for now let's just inherit the superclass method.
-  #
   # A getter for selection settings. See `Lifer::Collection#setting` for more
   # information.
   #
+  # @fixme Getting selection settings may actually need to be different than
+  #   getting collection settings. But for now let's just inherit the
+  #   superclass method.
+  #
   # @return [String, Symbol, NilClass] The setting for the collection (or a
   #   fallback setting, or a default setting).
   def setting(...)

data/lib/lifer/shared/finder_methods.rb

@@ -1,8 +1,7 @@
 # This module provides simple finder methods to classes that need to keep track
 # of their descendant classes.
 #
-# Example usage:
-#
+# @example Usage
 #     class MyClass
 #       included Lifer::Shared::FinderMethods
 #       # ...

data/lib/lifer/templates/config.yaml

@@ -32,6 +32,13 @@ uri_strategy: simple
 ###   uri_strategy: pretty
 ###
 ###   layout_file: path/to/my_other_layout.html.erb
+###
+### my_with_fine_grained_rss_settings:
+###   rss
+###     count: 99
+###     format: rss
+###     managing_editor: editor@example.com (Managing Editor)
+###     url: custom.xml
 
 # Selections
 #

data/lib/lifer/utilities.rb

@@ -14,16 +14,15 @@ module Lifer::Utilities
     end
 
     # Given a string path, classify it into a namespaced Ruby constant. If the
-    # constant does not exist, we raise a helpful error. For example:
+    # constant does not exist, we raise a helpful error.
     #
-    #    Given:  my/class_name/that_exists
-    #    Result: My::ClassName::ThatExists
+    # @example Result
+    #    classify("my/class_name/that_exists") #=> My::ClassName::ThatExists
     #
-    # FIXME:
-    # Note that this method is currently a bit naive. It cannot politely
-    # transform classes with many caps in them (i.e. `URIStrategy`) without
-    # being given an exact match (`URIStrategy`) or a broken-looking one
-    # (`u_r_i_strategy`).
+    # @fixme Note that this method is currently a bit naive. It cannot politely
+    #   transform classes with many caps in them (i.e. `URIStrategy`) without
+    #   being given an exact match (`URIStrategy`) or a broken-looking one
+    #   (`u_r_i_strategy`).
     #
     # @param string_constant [String] A string that maps to a Ruby constant.
     # @return [Class, Module]

data/lib/lifer/version.rb

@@ -1,3 +1,3 @@
 module Lifer
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/lifer.rb

@@ -63,7 +63,7 @@ module Lifer
 
     # A set of all entries currently in the project.
     #
-    # FIXME: Do we need this as well as `Lifer.manifest`?
+    # @fixme Do we need this as well as `Lifer.manifest`?
     #
     # @return [Set] All entries.
     def entry_manifest = brain.entry_manifest
@@ -85,7 +85,7 @@ module Lifer
 
     # A set of all entries currently in the project.
     #
-    # FIXME: Do we need this as well as `Lifer.manifest`?
+    # @fixme Do we need this as well as `Lifer.manifest`?
     #
     # @return [Set] All entries.
     def manifest = brain.manifest
@@ -99,8 +99,7 @@ module Lifer
     # Register new settings so that they are "safe" and can be read from a Lifer
     # configuration file. Unregistered settings are ignored.
     #
-    # Example usage:
-    #
+    # @example Usage
     #    register_settings(
     #      :hidden,
     #      :birthday,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lifer
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - benjamin wil
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-02 00:00:00.000000000 Z
+date: 2025-03-03 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.6.1/README.md
-  source_code_uri: https://github.com/benjaminwil/lifer/tree/0.6.1
+  homepage_uri: https://github.com/benjaminwil/lifer/blob/0.7.0/README.md
+  source_code_uri: https://github.com/benjaminwil/lifer/tree/0.7.0
   changelog_uri: https://github.com/benjaminwil/lifer/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []