lifer 0.12.4 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56e9416088ac954ed5ede64c4f4675153d8d6fb0a0a1d6cc04b91d387538c388
-  data.tar.gz: 638c9b87b742d4aa393bc312649f6d5801d855fd3c95dc16fb774c6d5a415fd2
+  metadata.gz: b4416a9edb890d8d98adc06d1baf7e58b695d85da827b48005d7285b6f5a1dbe
+  data.tar.gz: 0c45a40304601d473c946315ddea56860041339e029467f8bcecb603ca70a58a
 SHA512:
-  metadata.gz: 2b65f34b010f2117b52598cb10586717c13bac9ecb5bae417968fcf8919ab0128bb266e8ff02de7ac31ff578e4525e067423c2ad78bbaaeb594a9a81cc14d23b
-  data.tar.gz: df56506ab2cc5d0fae8a7714e59d0dc2a55b01ccbf77f07e787e8f0ee6d3995120b2b42c3ebd8f71f8ef69a720467cd396c7f0554374629d1f9eeb4a4f1049fc
+  metadata.gz: b8aa3c53f350191b59ff5105ac1130c62c4a2f690aca83794877b933e7d7bfa23e501d2c91bd90dfc4954a4db9edf57b5db8ea4c4bf75fe78aa3e3e3e7e20e0c
+  data.tar.gz: f9b729936ec8ef025d9bc6dc8b6deab6d4d63c1d281da50e99df5932cd1f245c581c911378a703f1ddb7e6a5167f21fa746a780ac9e9ad72f29721d93bf34215

data/CHANGELOG.md

@@ -1,4 +1,33 @@
 ## Next
+## v0.14.0
+
+This release includes some really nice improvements and bug fixes:
+
+- When returning a list of entries belonging to a `Lifer::Collection` or a
+  `Lifer::Tag`, the entries are now returned in reverse chronological order
+  by default. (But you can pass the argument `order: :oldest` to get them
+  in reverse, if you want.)
+- We fixed a bug where entries in `.html.erb` format that attempted to render
+  view partials would error out due to the `render` method not having been
+  defined with the context of the entry being built yet. This bug was a bit
+  unpleasant to reason about, but it resolves a major defect with ERB building.
+- The included Lifer configuration file template now enables the
+  JSON Feed builder by default.
+- Every `Lifer::Selection` name is now automatically registered as a setting so
+  that you can configure it like you configure any other collection of entries.
+- Lastly, this release removes `Lifer.manifest`. (A collection of absolute
+  paths to every entry file ended up not being incredibly useful. We get
+  the same-ish functionality from `Lifer.entry_manifest`.)
+
+## v0.13.0
+
+This release allows projects to build JSON Feed 1.1. Now, a project can
+build both Atom (or RSS 2.0) and JSON Feed, which is nice. In order to
+support JSON Feed, we modelled out `Lifer::Asset` and `Lifer::Author`. This
+is because JSON Feed explicitly supports author objects (with name, URL,
+and avatars URLs), and images and banner images per feed item.
+
+This release also improves the documentation for the `Lifer::Builder::RSS`.
 
 ## v0.12.4
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lifer (0.12.4)
+    lifer (0.14.0)
       base64
       i18n (< 2)
       kramdown (~> 2.4)

data/guix.scm

@@ -0,0 +1,19 @@
+(use-modules (guix)
+             (guix build-system gnu)
+             ((guix licenses) #:prefix license:)
+             (gnu packages ruby)
+             (gnu packages serialization))
+
+(package
+ (name "ruby-lifer-dev")
+ (version "0.12.4-git")
+ (source #f)
+ (build-system gnu-build-system)
+ (inputs
+  (append (list ruby libyaml)))
+ (synopsis "Another Ruby-based static website generator")
+ (description
+  "A ruby-based static website generator focused on extensibility and having
+  few dependencies.")
+ (home-page "https://github.com/benjaminwil/lifer")
+ (license license:expat))

data/lib/lifer/asset.rb

@@ -0,0 +1,82 @@
+class Lifer::Asset
+  # An asset is a file, often a multimedia file, that belongs to one or
+  # many entries. Right now, assets don't have much functionality of their
+  # own, but it's valuable to know what entries an asset has a relationship
+  # with. In the future, it may be valuable for us to build out functionality
+  # that allows users to have one or more asset hosts. This allows files that
+  # aren't checked into version control still be treated as entry dependencies.
+  #
+  class << self
+    # Builds or updates a Lifer asset. On update, this list of an asset's
+    # entries would get freshened.
+    #
+    # @param url [String] An absolute URL or path relative to the host root.
+    # @param entries [Array<Lifer::Entry>] An array of entries that the asset
+    #   belongs to.
+    # @return [Lifer::Asset] The new or updated asset.
+    def build_or_update(url: nil, entries: [])
+      update(url:, entries:) || build(url:, entries:)
+    end
+
+    # The default host for all assets.
+    #
+    # @return [String] A URL to a host. (Default: the configured global host.)
+    def default_host = Lifer.setting(:global, :host)
+
+    private
+
+    def build(url:, entries:)
+      if (new_asset = new(url:, entries:))
+        Lifer.asset_manifest << new_asset
+      end
+      new_asset || false
+    end
+
+    def update(url:, entries:)
+      normalized_url = Lifer::Utilities.uri_from url,
+        host: default_host,
+        object_type: self
+
+      if (asset = Lifer.asset_manifest.detect { _1.url == normalized_url })
+        asset.instance_variable_set :@entries,
+          (asset.instance_variable_get(:@entries) | entries)
+      end
+      asset || false
+    end
+
+  end
+
+  attr_reader :url, :entries
+
+  def initialize(url:, entries:)
+    normalized_url = Lifer::Utilities.uri_from url,
+      host: self.class.default_host,
+      object_type: self
+
+    @url = normalized_url
+    @entries = entries
+  end
+
+  # Checks whether a given URL matches the current asset's URL.
+  #
+  # @param url [String] A URL.
+  # @param host [String] The host URL. (Default: The configured global host
+  #   URL.)
+  # @return [boolean] Whether the given URL matches the object's URL.
+  def match?(url:, host: self.class.default_host)
+    @url == Lifer::Utilities.uri_from(url, host:, object_type: self.class)
+  end
+
+  # Gets the current URL. If given a host, the asset's true host will be
+  # replaced with the given host.
+  #
+  # @param host [String] A host URL. (Default: The configured global host URL.)
+  # @return [String] The URL to the current asset.
+  def url(host: self.class.default_host)
+    return @url if host == self.class.default_host
+
+    path = URI(@url).path
+
+    Lifer::Utilities.uri_from(path, host:, object_type: self.class)
+  end
+end

data/lib/lifer/author.rb

@@ -0,0 +1,106 @@
+module Lifer
+  # An author is a representation of a unique author of entries in the current
+  # project. This allows us to refer to an author's name in an entry's
+  # frontmatter, i.e.:
+  #
+  #     ---
+  #     title: My blog post
+  #     author: Nat McCartney
+  #     ---
+  #
+  # And let that reference load in a bunch of other metadata about the
+  # author. While it's possible to add all of this metadata at the entry level,
+  # the first entry loaded will be the source of truth for every reference
+  # back to the author. So it's preferrable to set the author metadata in your
+  # global configuration:
+  #
+  #    # my-lifer.conf
+  #    authors:
+  #      - name: Nat McCartney
+  #        url: https://example.com/nat
+  #        avatar: https://example.com/nat.png
+  #
+  # Within a Lifer project, this allows you to do powerful things like get
+  # a list of entries by a unique author (or set of authors). It also allows
+  # you to provide author-specific URLs and avatar images in your website's
+  # JSON Feeds.
+  #
+  # The author's name is used as the primary identifier. We have tried to be
+  # smart about this so that, for example, "Nat McCartney", "nat mccartney",
+  # and "nat-mccartney" will all load up the same author object.
+  #
+  class Author
+    class << self
+      # Builds or updates a Lifer author. On update, the list of an author's
+      # entries would get freshened.
+      #
+      # @param name [String] The name of the author.
+      # @param url [String] A relative or absolute URL to learn more about
+      #   the author at.
+      # @param avatar [String] A relative or absolute URL to an image that
+      #   represents the author.
+      # @return [Lifer::Author] The new or updated author.
+      def build_or_update(name:, url: nil, avatar: nil, entries: [])
+        update(name:, url:, avatar:, entries:) ||
+          build(name:, url:, avatar:, entries:)
+      end
+
+      private
+
+      def build(name:, url:, avatar:, entries:)
+        if (new_author = new(name:, url:, avatar:, entries:))
+          Lifer.author_manifest << new_author
+        end
+        new_author || false
+      end
+
+      def update(name:, url:, avatar:, entries:)
+        author_id = Lifer::Utilities.handleize(name)
+
+        if (author = Lifer.authors.detect { _1.id == author_id })
+          author.instance_variable_set :@entries,
+            (author.instance_variable_get(:@entries) | entries)
+        end
+        author || false
+      end
+    end
+
+    attr_reader :name, :entries
+
+    def initialize(name:, url:, avatar:, entries:)
+      @name = name
+      @url = url
+      @avatar = avatar
+      @entries = entries
+    end
+
+    # An avatar image URL that represents the author. The URL can either be
+    # relative from the website's root or an absolute URL. If the relative or
+    # absolute URL is ambiguous, it is sanitized and this method returns nil.
+    #
+    # @param host [String] The host to prefix to relative URLs. By default,
+    # this is the Lifer project's global host.
+    # @return [String] The absolute URL to the avatar image.
+    def avatar(host: Lifer.setting(:global, :host))
+      Lifer::Utilities.uri_from(@avatar, host:, object_type: self.class)
+    end
+
+    # An identifier built from the author's name. This uses our generic
+    # handle-izer function. So a name like "Nat McCartney" becomes
+    # "nat-mccartney".
+    #
+    # @return [String] The identifier for the author.
+    def id = (@id ||= Lifer::Utilities.handleize(name))
+
+    # A URL that provides more info about the author. The URL can either be
+    # relative from the website's root or an absolute URL. If the relative or
+    # absolute URL is ambiguous, it is sanitized and this method returns nil.
+    #
+    # @param host [String] The host to prefix to relative URLs. By default,
+    # this is the Lifer project's global host.
+    # @return [String] The absolute version of the URL.
+    def url(host: Lifer.setting(:global, :host))
+      Lifer::Utilities.uri_from(@url, host:, object_type: self.class)
+    end
+  end
+end

data/lib/lifer/brain.rb

@@ -25,6 +25,27 @@ class Lifer::Brain
     def init(root: Dir.pwd, config_file: nil) = new(root:, config_file:)
   end
 
+  # The asset manifest tracks the unique assets added to the project as they
+  # are added. The writer methods for this instanc evariable is used internally
+  # by Lifer when adding new assets.
+  #
+  # @return [Set<Lifer::Asset>]
+  def asset_manifest = (@asset_manifest ||= Set.new)
+
+  # Given the author manifest, this returns an array of all authors for the
+  # current project. This method is preferrable for accessing and querying for
+  # authors.
+  #
+  # @return [Array<Lifer::Author>]
+  def authors = author_manifest.to_a
+
+  # The author manifest tracks the unique authors added to the project as
+  # they are added. The writer method for this instance variable is used
+  # internally by Lifer when adding new authors.
+  #
+  # @return [Set<Lifer::Author>]
+  def author_manifest = (@author_manifest ||= Set.new)
+
   # Destroy any existing build output and then build the Lifer project with all
   # configured `Lifer::Builder`s.
   #
@@ -73,17 +94,12 @@ class Lifer::Brain
   # @return [Lifer::Config] The Lifer configuration object.
   def config = (@config ||= Lifer::Config.build file: config_file_location)
 
-  # Returns all entries that have been added to the manifest. If all is working
-  # as intended, this should be every entry ever generated.
+  # Allows for getting the entry manifest or shovelling new entries to the
+  # entry manifest.
   #
   # @return [Set<Lifer::Entry>] All entries that currently exist.
   def entry_manifest = (@entry_manifest ||= Set.new)
 
-  # A manifest of all Lifer project entries.
-  #
-  # @return [Set<Lifer::Entry>] A set of all entries.
-  def manifest = (@manifest ||= Set.new)
-
   # Returns the build directory for the Lifer project's build output.
   #
   # @return [String] The Lifer build directory.

data/lib/lifer/builder/html/from_any.rb

@@ -18,7 +18,7 @@ class Lifer::Builder
       # should be expected to.
       #
       # @raise [NotImplementedError]
-      def render
+      def render(_path, _locals, _context)
         raise NotImplementedError,
           "subclasses must implement a custom `#render` method"
       end

data/lib/lifer/builder/html/from_erb.rb

@@ -11,7 +11,7 @@ class Lifer::Builder::HTML
   #       </head>
   #
   #       <body>
-  #         <%= partial "_layouts/header.html.erb" %>
+  #         <%= render "_layouts/header.html.erb" %>
   #
   #         <h1><%= my_collection.name %></h1>
   #
@@ -23,7 +23,7 @@ class Lifer::Builder::HTML
   #           </section>
   #         <% end %>
   #
-  #         <%= partial "_layouts/footer.html.erb" %>
+  #         <%= render "_layouts/footer.html.erb" %>
   #       </body>
   #     </html>
   #
@@ -101,16 +101,20 @@ class Lifer::Builder::HTML
         collections = collection_context_class.new Lifer.collections
         tags = tag_context_class.new Lifer.tags
 
-        binding.local_variable_set :collections, collections
-        binding.local_variable_set :settings, Lifer.settings
-        binding.local_variable_set :tags, tags
-        binding.local_variable_set :content,
-          ERB.new(entry.to_html).result(binding)
+        current_binding = binding
+        current_binding.local_variable_set :collections, collections
+        current_binding.local_variable_set :settings, Lifer.settings
+        current_binding.local_variable_set :tags, tags
 
         define_singleton_method :render,
           -> (relative_path_to_template, locals = {}) {
-            partial_render_method relative_path_to_template, locals
+            partial_render_method relative_path_to_template,
+              locals,
+              current_binding
           }
+
+        current_binding.local_variable_set :content,
+          ERB.new(entry.to_html).result(binding)
       }
     end
 
@@ -130,21 +134,23 @@ class Lifer::Builder::HTML
     # available from entry and layout templates.
     #
     # @example Usage
-    #    <%= partial "_layouts/my_partial.html.erb", id: "123" %>
+    #    <%= render "_layouts/my_partial.html.erb", id: "123" %>
     # @param relative_path_to_template [String] The path, from the Lifer root,
     #   to the partial layout file.
     # @param locals [Hash] Additional data that should be passed along for
     #   rendering the partial.
+    # @param source_binding [Binding] A binding object carrying context
+    #   required to render the current partial layout.
     # @return [String] The rendered partial document.
-    def partial_render_method(relative_path_to_template, locals)
+    def partial_render_method(relative_path_to_template, locals, source_binding)
       template_path = File.join(Lifer.root, relative_path_to_template)
 
       partial_binding = binding.tap { |binding|
-        context.local_variables.each do |variable|
+        source_binding.local_variables.each do |variable|
           next if variable == :content
 
           binding.local_variable_set variable,
-            context.local_variable_get(variable)
+            source_binding.local_variable_get(variable)
         end
 
         locals.each do |key, value|

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

@@ -0,0 +1,33 @@
+module Lifer::Builder::HTML::FromLiquid::Drops
+  class AuthorDrop < Liquid::Drop
+    attr_accessor :lifer_author
+
+    def initialize(lifer_author) = (@lifer_author = lifer_author)
+
+    def avatar = (@avatar ||= lifer_author.avatar)
+
+    def name = (@name ||= lifer_author.name)
+
+    def url = (@url ||= lifer_author.url)
+
+    def entries
+      @entries ||= lifer_author.entries.map {
+        EntryDrop.new _1, collection: _1.collection, tags: _1.tags
+      }
+    end
+  end
+
+  class AuthorsDrop < Liquid::Drop
+    attr_accessor :authors
+
+    def initialize(lifer_authors)
+      @authors = lifer_authors.map { AuthorDrop.new _1 }
+    end
+
+    def each(&block)
+      authors.each(&block)
+    end
+
+    def to_a = @authors
+  end
+end

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

@@ -25,7 +25,9 @@ module Lifer::Builder::HTML::FromLiquid::Drops
     # The entry authors (or author).
     #
     # @return [String]
-    def authors = (@authors ||= lifer_entry.authors.join(", "))
+    def authors
+      @authors ||= AuthorsDrop.new(lifer_entry.authors)
+    end
 
     # The entry content.
     #

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

@@ -8,6 +8,7 @@ class Lifer::Builder::HTML::FromLiquid
   module Drops; end
 end
 
+require_relative "drops/authors_drop"
 require_relative "drops/collection_drop"
 require_relative "drops/collections_drop"
 require_relative "drops/entry_drop"

data/lib/lifer/builder/html.rb

@@ -116,7 +116,7 @@ class Lifer::Builder::HTML < Lifer::Builder
   #   entry cannot be output to HTML.  We should not care about this return
   #   value.
   def generate_output_file_for(entry)
-    return unless entry.class.output_extension == :html
+    return unless entry.output_extension == :html
 
     relative_path = output_file entry
     absolute_path = File.join(Lifer.output_directory, relative_path)

data/lib/lifer/builder/json_feed.rb

@@ -0,0 +1,214 @@
+require "fileutils"
+
+class Lifer::Builder
+  # This builds JSON feed compliant with the JSON Feed 1.1
+  # specification[1]. Note that we don't currently support *all* of the features
+  # of JSON Feed, but it shouldn't be too hard to add them.
+  #
+  # The JSON Feed builder can be configured in a number of ways:
+  #
+  # 1. Boolean
+  #
+  #    Simply set `json_feed: true` or `json_feed: false` to enable or disable
+  #    a feed for a collection. If `true`, a JSON feed will be build to
+  #    `/name-of-collection.json` at the root of the Lifer output directory.
+  #
+  # 2. Simple
+  #
+  #    Simply set `json_feed: name-of-output-file.json` to specify the name of
+  #    the output JSON Feed file.
+  #
+  # 3. Fine-grained
+  #
+  #    Provide an object under `json_feed:` for more fine-grained control over
+  #    configuration. The following sub-settings are supported:
+  #
+  #    - `authors:` A list of authors to fall back to if an entry does not
+  #      have its own authors data. Each author can include the following fields:
+  #        - `name:` The author's name.
+  #        - `url:` A URL that represents the author.
+  #        - `avatar:` The URL to an avatar that represents the author.
+  #    - `content_format:` The format of the feed entries for the entire feed.
+  #      Either `html` or `text`. (Default: `html`.)
+  #    - `count:` - The limit of JSON Feed items that should be included in the
+  #      output document. Leave unset or set to `0` to include all entries.
+  #    - `expired:` Set the expired flag on the feed to broadcast whether
+  #      the feed will continue to be updated.
+  #    - `home_page_url:` A URL that represents the home page of the current
+  #      feed.
+  #    - `url:` The path to the filename of the output JSON Feed file.
+  #
+  # [1] https://www.jsonfeed.org/version/1.1/
+  #
+  class JSONFeed < Lifer::Builder
+    # As of this writing, we support the latest version of the JSON Feed
+    # specification.
+    #
+    JSON_FEED_VERSION = "1.1"
+
+    self.name = :json_feed
+    self.settings = [
+      json_feed: [
+        {authors: [:name, :url, :avatar]},
+        :content_format,
+        :count,
+        :expired,
+        :home_page_url,
+        :url
+      ]
+    ]
+
+    class << self
+      # Traverses and renders a JSON Feed for each JSON Feed-enabled, feedable
+      # collection in the configured output directory for the Lifer project.
+      #
+      # @param root [String] The Lifer root.
+      # @return [void]
+      def execute(root:)
+        Dir.chdir Lifer.output_directory do
+          new(root:).execute
+        end
+      end
+    end
+
+    # Traverses and renders a JSON Feed for JSON Feed-enabled feedable
+    # collections.
+    #
+    # @return [void]
+    def execute
+      collections_with_feeds.each do |collection|
+        next unless (filename = output_filename(collection))
+
+        FileUtils.mkdir_p File.dirname(filename)
+
+        File.open filename, "w" do |file|
+          file.puts(
+            json_feed_for(collection) do |current_feed|
+              max_index = max_feed_items(collection) - 1
+
+              collection.entries
+                .select { |entry| entry.feedable? }[0..max_index]
+                .each { |entry| json_feed_entry(current_feed, entry, collection) }
+            end
+          )
+        end
+      end
+    end
+
+    private
+
+    attr_reader :collections_with_feeds, :root
+
+    def initialize(root:)
+      @collections_with_feeds =
+        Lifer.collections.select { |collection| collection.setting :json_feed }
+      @root = root
+    end
+
+    # Builds an entry in the JSON Feed given the current JSON Feed being
+    # built, a Lifer entry, and a Lifer collection.
+    #
+    # @param feed_object [Hash] JSON Feed currently being built.
+    # @param lifer_entry [Lifer::Entry] The Lifer entry to build an entry for.
+    # @param lifer_collection [Lifer::Collection] The Lifer collection for
+    #   the entry. This provides additional context that may be required
+    #   for some parts of JSON Feed entry schema.
+    # @return [void] The entry is added to the JSON Feed as a side effect
+    #   by the end of this procedure.
+    def json_feed_entry(feed_object, lifer_entry, lifer_collection)
+      feed_item_object = {
+        id: lifer_entry.permalink,
+        url: lifer_entry.permalink,
+        external_url: lifer_entry.frontmatter[:external_url],
+        title: lifer_entry.title,
+        summary: lifer_entry.summary,
+        image: lifer_entry.assets.detect { |asset|
+          asset.match?(
+            url: lifer_entry.frontmatter[:image] ||
+              lifer_entry.frontmatter[:images]&.first
+          )
+        }&.url,
+        banner_image: lifer_entry.assets.detect { |asset|
+          asset.match? url: lifer_entry.frontmatter[:banner_image]
+        }&.url,
+        date_published: lifer_entry.published_at,
+        date_modified: lifer_entry.updated_at(fallback: lifer_entry.published_at),
+        tags: lifer_entry.tags,
+        language: lifer_collection.setting(:language)
+      }
+
+      feed_content_format =
+        lifer_collection.setting(:json_feed, :content_format)&.to_sym || :html
+      case feed_content_format
+      when :html
+        feed_item_object[:content_html] = lifer_entry.to_html
+      when :text
+        # Currently, `Entry#to_html` is just the name of the method we use
+        # to get the entry content, regardless of whether the entry output is
+        # HTML or not.
+        feed_item_object[:content_text] = lifer_entry.to_html
+      end
+
+      if (authors = lifer_entry.authors).any?
+        feed_item_object[:authors] = authors.map { |author|
+          {
+            name: author.name,
+            avatar: author.avatar,
+            url: author.url
+          }.reject { |_key, value| value.nil? }
+        }
+      end
+
+      feed_object[:items] << feed_item_object
+    end
+
+    # Provides the entire feed object for serialization.
+    #
+    # Note that we don't currently support JSON Feed 1.1 *exhaustively*. For
+    # example, we don't currently support pagniation or hubs. Here's a list
+    # of root-level 1.1 fields we do not currently support:
+    #
+    #   - authors
+    #   - favicon
+    #   - hubs
+    #   - icon
+    #   - next_url
+    #   - user_comment
+    #
+    # @param collection [Lifer::Collection] The current Lifer collection for
+    #   metadata context.
+    # @return [String] The JSON representation of the JSON Feed.
+    def json_feed_for(collection, &block)
+      feed_object = {
+        version: JSON_FEED_VERSION,
+        title: collection.setting(:title),
+        description: collection.setting(:description) || collection.setting(:site_title),
+        expired: collection.setting(:json_feed, :expired, strict: true),
+        feed_url: collection.setting(:json_feed, :url, strict: true),
+        home_page_url: collection.setting(:json_feed, :home_page_url, strict: true),
+        language: collection.setting(:language),
+        items: []
+      }
+      feed_object = feed_object.reject { |_key, value| value.nil? }
+
+      yield feed_object
+
+      feed_object.to_json
+    end
+
+    def max_feed_items(collection) = collection.setting(:json_feed, :count) || 0
+
+    def output_filename(collection)
+      strict = !collection.root?
+
+      case collection.setting(:json_feed, strict:)
+      when FalseClass, NilClass then nil
+      when TrueClass then File.join(Dir.pwd, "#{collection.name}.json")
+      when Hash
+        File.join Dir.pwd, collection.setting(:json_feed, :url, strict:)
+      when String
+        File.join Dir.pwd, collection.setting(:json_feed, strict:)
+      end
+    end
+  end
+end

data/lib/lifer/builder/rss.rb

@@ -15,7 +15,8 @@ require "rss"
 # 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`
+#    collection. If `true`, an RSS feed will be built to
+#    `/name-of-collection.xml` at the root of the Lifer output directory.
 #
 # 2. Simple
 #
@@ -78,8 +79,8 @@ class Lifer::Builder::RSS < Lifer::Builder
   ]
 
   class << self
-    # Traverses and renders an RSS feed for each feedable collection in the
-    # configured output directory for the Lifer project.
+    # Traverses and renders an RSS feed for each RSS-enabled feedable
+    # collection in the configured output directory for the Lifer project.
     #
     # @param root [String] The Lifer root.
     # @return [void]
@@ -98,7 +99,7 @@ class Lifer::Builder::RSS < Lifer::Builder
     DEFAULT_MAKER_FORMAT_NAME
   end
 
-  # Traverses and renders an RSS feed for feedable collection.
+  # Traverses and renders an RSS feed for RSS-enabled feedable collections.
   #
   # @return [void]
   def execute

data/lib/lifer/builder/txt.rb

@@ -56,7 +56,7 @@ class Lifer::Builder::TXT < Lifer::Builder
   end
 
   def generate_output_file_for(entry)
-    return unless entry.class.output_extension == :txt
+    return unless entry.output_extension == :txt
 
     relative_path = output_file entry
     absolute_path = File.join(Lifer.output_directory, relative_path)

data/lib/lifer/builder.rb

@@ -101,4 +101,5 @@ end
 
 require_relative "builder/rss"
 require_relative "builder/html"
+require_relative "builder/json_feed"
 require_relative "builder/txt"

data/lib/lifer/collection.rb

@@ -32,12 +32,13 @@ class Lifer::Collection
         .select { |candidate| Lifer::Entry.supported? candidate }
 
       entries = entry_glob.select { |entry|
-        if Lifer.manifest.include? entry
+        filenames = Lifer.entry_manifest.map(&:file)
+
+        if filenames.include? entry
           false
         elsif Lifer.ignoreable? entry.gsub("#{directory}/", "")
           false
         else
-          Lifer.manifest << entry
           true
         end
       }.map { |entry| Lifer::Entry.generate file: entry, collection: }
@@ -89,6 +90,8 @@ class Lifer::Collection
   #
   # @param name [*Symbol] A list of symbols that map to a nested Lifer
   #   setting (for the current collection).
+  #   @param strict [boolean] Choose whether to strictly return the collection
+  #     setting or to fallback to the Lifer root and default settings.
   # @return [String, Nil] The setting as set in the Lifer project's
   #   configuration file.
   def setting(*name, strict: false)

data/lib/lifer/config.rb

@@ -1,5 +1,3 @@
-require_relative "utilities"
-
 # This class is responsible for reading the Lifer configuration YAML file. This
 # file should provided by the user, but the Lifer Ruby gem does provide a default
 # file, as well.

data/lib/lifer/entry/markdown.rb

@@ -2,8 +2,6 @@ require "date"
 require "kramdown"
 require "time"
 
-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

data/lib/lifer/entry.rb

@@ -29,6 +29,11 @@ module Lifer
     require_relative "entry/markdown"
     require_relative "entry/txt"
 
+    # If assets are represented in YAML frontmatter as a string, they're split on
+    # commas and/or spaces.
+    #
+    ASSET_DELIMITER_REGEX = /[,\s]+/
+
     # We provide a default date for entries that have no date and entry types that
     # otherwise could not have a date due to no real way of getting that metadata.
     #
@@ -58,12 +63,15 @@ module Lifer
       # @param file [String] The absolute filename of an entry file.
       # @param collection [Lifer::Collection] The collection for the entry.
       # @return [Lifer::Entry] An entry.
-      def generate(file:, collection:)
+      def generate(file:, collection:, dependencies: [:assets, :authors, :tags])
         error!(file) unless File.exist?(file)
 
         if (new_entry = subclass_for(file)&.new(file:, collection:))
           Lifer.entry_manifest << new_entry
-          new_entry.tags
+
+          dependencies.each do |dependency|
+            new_entry.public_send dependency
+          end
         end
 
         new_entry
@@ -124,6 +132,14 @@ module Lifer
       @collection = collection
     end
 
+    # Locates and returns all assets defined in the entry.
+    #
+    # @return [Array<Lifer::Asset>] The entry's assets.
+    def assets
+      @assets ||= candidate_asset_names
+        .map { Lifer::Asset.build_or_update(url: _1, entries: [self]) }
+    end
+
     # Given the entry's frontmatter, we should be able to get a list of authors.
     # We always prefer authors (as opposed to a singular author) because it makes
     # handling both cases easier in the long run.
@@ -133,7 +149,20 @@ module Lifer
     #
     # @return [Array<String>] An array of authors's names.
     def authors
-      Array(frontmatter[:author] || frontmatter[:authors]).compact
+      list = Array(frontmatter[:author] || frontmatter[:authors]).compact
+      if list.any? && list.all? { _1.is_a? Array }
+        list = [list.to_h]
+      end
+
+      list.map {
+        attributes = Lifer::Utilities.symbolize_keys(
+          case _1
+          when Hash then _1
+          when String then {name: _1}
+          end
+         )
+        Lifer::Author.build_or_update **attributes.merge(entries: [self])
+      }
     end
 
     # This method returns the full text of the entry, only removing the
@@ -176,6 +205,12 @@ module Lifer
       @full_text ||= File.readlines(file).join if file
     end
 
+    # The file extension to be used when at the entry's build time. For
+    # example, a Markdown file should be built to HTML.
+    #
+    # @return [String]
+    def output_extension = self.class.output_extension
+
     # Using the current Lifer configuration, we can calculate the expected
     # permalink for the entry. For example:
     #
@@ -284,6 +319,21 @@ module Lifer
 
     private
 
+    # Similar to tags, users may represent assets as a string or a list of
+    # strings instead of YAML-style arrays. So let's parse for all of them.
+    #
+    # @return [Array<String>] An array of candidate asset URLs.
+    def candidate_asset_names
+      candidate_frontmatter_fields = [:banner_image, :image, :images]
+      candidate_frontmatter_fields.flat_map {
+        case frontmatter[_1]
+        when Array then frontmatter[_1].map(&:to_s)
+        when String then frontmatter[_1].split(ASSET_DELIMITER_REGEX)
+        else []
+        end.uniq
+      }.compact
+    end
+
     # It is conventional for users to use spaces or commas to delimit tags in
     # other systems, so let's support that. But let's also support YAML-style
     # arrays.

data/lib/lifer/selection.rb

@@ -6,7 +6,7 @@
 # detected Ruby files are dynamically loaded when `Lifer::Brain` is initialized.
 #
 # Implementing a selection is simple. Just implement the `#entries` method and
-# rovide a name. The `#entries` method can be used to filter down
+# provide a name. The `#entries` method can be used to filter down
 # `Lifer.entry_manifest` in whichever way one needs. To see examples of this,
 # check out the source code of any of the included selections.
 #
@@ -25,7 +25,9 @@ class Lifer::Selection < Lifer::Collection
     #
     # @return [Lifer::Selection]
     def generate
-      new(name: name, directory: nil)
+      selection = new(name: name, directory: nil)
+      Lifer.register_settings name
+      selection
     end
 
     private

data/lib/lifer/tag.rb

@@ -43,11 +43,22 @@ module Lifer
 
     attr_accessor :name
 
-    attr_reader :entries
-
     def initialize(name:, entries:)
       @name = name
       @entries = entries
     end
+
+    # Returns the tag's associated entries in order.
+    #
+    # @param order [Symbol] Either :latest (descending) or :oldest (ascending).
+    # @return [Array<Lifer::Entry>] The entries for the current tag.
+    def entries(order: :latest)
+      case order
+      when :latest
+        @entries.sort_by { |entry| entry.published_at }.reverse
+      when :oldest
+        @entries.sort_by { |entry| entry.published_at }
+      end
+    end
   end
 end

data/lib/lifer/templates/config.yaml

@@ -8,6 +8,7 @@ author: Admin
 entries:
   default_title: Untitled Entry
 
+json_feed: false
 rss: false
 uri_strategy: simple
 
@@ -33,12 +34,24 @@ uri_strategy: simple
 ###
 ###   layout_file: path/to/my_other_layout.html.erb
 ###
-### my_with_fine_grained_rss_settings:
-###   rss
+### my_collection_with_fine_grained_rss_settings:
+###   json_feed:
+###     authors:
+###       - name: Hal Human
+###         avatar: /images/avatars/hal.png
+###         url: https://hals-website.local
+###     content_format: html
+###     count: 99
+###     expired: false
+###     home_page_url: https://example.com/my-collection
+###     url: /location-of-the-feed.json
+###
+###   rss:
 ###     count: 99
 ###     format: rss
 ###     managing_editor: editor@example.com (Managing Editor)
 ###     url: custom.xml
+###
 
 # Selections
 #
@@ -79,6 +92,7 @@ global:
   build:
     - html
     - rss
+    - json_feed
     - txt
   host: https://example.com
   output_directory: _build

data/lib/lifer/uri_strategy.rb

@@ -59,7 +59,7 @@ class Lifer::URIStrategy
 
   private
 
-  def file_extension(entry) = entry.class.output_extension
+  def file_extension(entry) = entry.output_extension
 
   self.name = :uri_strategy
 end

data/lib/lifer/utilities.rb

@@ -4,6 +4,8 @@ require "parallel"
 # Ensure that these are actually useful globally, though. :-)
 #
 module Lifer::Utilities
+  class AmbiguousURIError < StandardError; end
+
   class << self
     # Output a string using bold escape sequences to the output TTY text.
     #
@@ -129,6 +131,23 @@ module Lifer::Utilities
       symbolized_hash
     end
 
+    def uri_from(string, host:, object_type:)
+      uri = string && URI.parse(string.strip)
+
+      if uri && uri.relative? && uri.to_s.start_with?("/")
+        "%s%s" % [host, uri]
+      elsif uri && uri.relative? && !uri.to_s.start_with?("/")
+        raise AmbiguousURIError
+      elsif uri&.absolute?
+        uri.to_s
+      end
+    rescue AmbiguousURIError
+      Lifer::Message.error "utilities.ambiguous_uri_error",
+        object_type: object_type.inspect,
+        uri: uri&.to_s
+      nil
+    end
+
     private
 
     def camelize(string)

data/lib/lifer/version.rb

@@ -1,3 +1,3 @@
 module Lifer
-  VERSION = "0.12.4"
+  VERSION = "0.14.0"
 end

data/lib/lifer.rb

@@ -29,6 +29,22 @@ module Lifer
   FRONTMATTER_REGEX = /^---\n(.*?)---\n/m
 
   class << self
+    # All of the assets represented in Lifer entries for the current project.
+    #
+    # @return [Array<Lifer::Asset>] The complete list of assets.
+    def asset_manifest = brain.asset_manifest
+
+    # All of the authors represented in Lifer entries for the current project.
+    #
+    # @return [Array<Lifer::Author>] The complete list of authors.
+    def authors = brain.authors
+
+    # A set of all authors added to the project. Prefer using the `#authors`
+    # method for author queries.
+    #
+    # @return [Set<Lifer::Author>] The complete set of author.
+    def author_manifest = brain.author_manifest
+
     # The first time `Lifer.brain` is referenced, we build a new `Lifer::Brain`
     # object that is used and reused until the current process has ended.
     #
@@ -65,9 +81,21 @@ module Lifer
     # @return [Pathname] The path to the current Lifer config file.
     def config_file = brain.config.file
 
-    # A set of all entries currently in the project.
-    #
-    # @fixme Do we need this as well as `Lifer.manifest`?
+    # Uses the entry manifest to return entries in the specified order.
+    #
+    # @param order [Symbol] Either :latest (descending) or :oldest (ascending).
+    # @return [Set] All entries in the specified order.
+    def entries(order: :latest)
+      case order
+      when :latest
+        entry_manifest.sort_by { |entry| entry.published_at }.reverse
+      when :oldest
+        entry_manifest.sort_by { |entry| entry.published_at }
+      end
+    end
+
+    # Allows for getting the entry manifest or shovelling new entries to the
+    # entry manifest.
     #
     # @return [Set] All entries.
     def entry_manifest = brain.entry_manifest
@@ -87,13 +115,6 @@ module Lifer
       directory_or_file.match?(/#{IGNORE_PATTERNS.join("|")}/)
     end
 
-    # A set of all entries currently in the project.
-    #
-    # @fixme Do we need this as well as `Lifer.manifest`?
-    #
-    # @return [Set] All entries.
-    def manifest = brain.manifest
-
     # The build directory for the Lifer project.
     #
     # @return [Pathname] The absolute path to the directory where the Lifer
@@ -173,11 +194,14 @@ require "i18n"
 I18n.load_path += Dir["%s/locales/*.yml" % Lifer.gem_root]
 I18n.available_locales = [:en]
 
-# `Lifer::Shared` contains modules that that may or may not be included on other
-# classes required below.
+# `Lifer::Shared` and `Lifer::Utilities` contain modules and methods that
+# are used by the main models required below.
 #
 require_relative "lifer/shared"
+require_relative "lifer/utilities"
 
+require_relative "lifer/asset"
+require_relative "lifer/author"
 require_relative "lifer/brain"
 require_relative "lifer/builder"
 require_relative "lifer/collection"

data/locales/en.yml

@@ -49,5 +49,6 @@ en:
     finder_methods:
       unknown_class: no class with name "%{name}"
   utilities:
+    ambiguous_uri_error: "An %{object_type} contains an ambiguous URI: \"%{uri}\". Use an absolute URI or relative from the project root instead."
     classify_error: >
       could not find constant for path "%{string_constant}" (%{camel_cased_string_constant})

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lifer
 version: !ruby/object:Gem::Version
-  version: 0.12.4
+  version: 0.14.0
 platform: ruby
 authors:
 - benjamin wil
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -168,7 +169,10 @@ files:
 - bin/console
 - bin/lifer
 - bin/setup
+- guix.scm
 - lib/lifer.rb
+- lib/lifer/asset.rb
+- lib/lifer/author.rb
 - lib/lifer/brain.rb
 - lib/lifer/builder.rb
 - lib/lifer/builder/html.rb
@@ -176,6 +180,7 @@ files:
 - lib/lifer/builder/html/from_erb.rb
 - lib/lifer/builder/html/from_liquid.rb
 - lib/lifer/builder/html/from_liquid/drops.rb
+- lib/lifer/builder/html/from_liquid/drops/authors_drop.rb
 - lib/lifer/builder/html/from_liquid/drops/collection_drop.rb
 - lib/lifer/builder/html/from_liquid/drops/collections_drop.rb
 - lib/lifer/builder/html/from_liquid/drops/entry_drop.rb
@@ -185,6 +190,7 @@ files:
 - lib/lifer/builder/html/from_liquid/drops/tags_drop.rb
 - lib/lifer/builder/html/from_liquid/filters.rb
 - lib/lifer/builder/html/from_liquid/liquid_env.rb
+- lib/lifer/builder/json_feed.rb
 - lib/lifer/builder/rss.rb
 - lib/lifer/builder/txt.rb
 - lib/lifer/cli.rb
@@ -223,9 +229,10 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/benjaminwil/lifer/blob/v0.12.4/README.md
-  source_code_uri: https://github.com/benjaminwil/lifer/tree/v0.12.4
+  homepage_uri: https://github.com/benjaminwil/lifer/blob/v0.14.0/README.md
+  source_code_uri: https://github.com/benjaminwil/lifer/tree/v0.14.0
   changelog_uri: https://github.com/benjaminwil/lifer/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -240,7 +247,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Minimal static weblog generator.
 test_files: []