lifer 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2f61316d5e10ff4212470b5539741a4204f35976f97d193ef7aabfd944c62a5
-  data.tar.gz: 03b9aafb098ab04f2aa1306fa34512d9627801d468910fb48cd5e10a736b7e47
+  metadata.gz: 1b6414082e8f6f1d9b18034f2f227890b85ac73b22ab50c25cb2e350812c1a90
+  data.tar.gz: 5891afc57d102fd67422bf581edc4de839b05efbe10d104529a817391c0e7cad
 SHA512:
-  metadata.gz: 5c1f46e3c16622144cc513b3496d4d0bb9f14231d1b92960b63249b3962753355ed92d5a27ed12ad3bd930e0e56ef871b4551bb4d888e11384191f5747580b19
-  data.tar.gz: bcc5771d87e311dfe52d1c2bc79d9386c8f3677b7f3eafb66100815a9d76b2c8e2b5ce60855424d276c1cc8d8fb5e1c42f2298c5d662edf1ee85d03f8ec1a9c8
+  metadata.gz: 7adb1041c558a2d60ef525bf1d12af4dd3d587a26f8ae0ef4e2f4c8fb9e04e14c648cf4bd72717aba143e747ccabe970ec1c859cd0c69b5259847887c0f99361
+  data.tar.gz: a9ec79fce82554f69ba1634ce414b7b63014c8545f8f8c5a6201c194d375d57d09a36128db4f6b242c279bfe0fe419f3b333034268415379c1b9138d372d352f

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 ## Next
 
+## v0.9.0
+
+Atom feeds now support entries with both `#published_at` and `#updated_at`
+timestamp. There is no standard equivalent way to provide this functonality for
+RSS-format feeds, unfortunately. As part of this change, we removed all
+`Entry#date` methods in favour of `Entry#published_at` onces. In Atom feeds, if
+an article has no last updated date, the publication date is used instead.
+
+Additionally, this release includes a new environment variable:
+`LIFER_UNPARALLELIZED`. You can use this environment variable to run `lifer
+build` or `lifer serve` without any parallelization turned on. This could be
+useful for reproducing bugs and so on. Example usage:
+
+    LIFER_UNPARALLELIZED=1 lifer build
+
+## v0.8.0
+
+### Tags
+
+Entries now support tag frontmatter. This introduces a new way of making
+associations between entries. Tags can encoded in entries as YAML arrays or as a
+string (with comma and/or space delimiters):
+
+    ---
+    title: My Entry
+    tags: beautifulTag, lovelyTag
+    ---
+
+    Blah blah blah.
+
+Then, in your ERB or Liquid templates you can get entries via tag:
+
+    <% tags.beautifulTag.entries.each do |entry| %>
+      <li><%= entry.title %></li>
+    <% end %>
+
+### Frontmatter support across all entry types
+
+Before this release, frontmatter was only supported by Markdown files. This
+started to be annoying, because of features I wanted like tags. I figured it
+couldn't hurt to just check any entry file for frontmatter, so that's how it
+works now.
+
 ## v0.7.0
 
 This release adds Atom feed support to the RSS builder. In your configuration

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lifer (0.7.0)
+    lifer (0.9.0)
       i18n (< 2)
       kramdown (~> 2.4)
       liquid (~> 5.6, < 6)
@@ -44,7 +44,7 @@ GEM
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     language_server-protocol (3.17.0.3)
-    liquid (5.8.1)
+    liquid (5.8.2)
       bigdecimal
       strscan (>= 3.1.1)
     listen (3.9.0)

data/lib/lifer/brain.rb

@@ -65,7 +65,7 @@ class Lifer::Brain
   # @return [Array<Lifer::Collection>] All the collections for the current Lifer
   #   project.
   def collections
-    @collections ||= generate_collections + generate_selections
+    @collections ||= (generate_collections + generate_selections).to_a
   end
 
   # Returns the Lifer project's configuration object.
@@ -139,6 +139,19 @@ class Lifer::Brain
     config.setting *name, collection_name: collection&.name, strict: strict
   end
 
+  # Given the tag manifest, this returns an array of all tags for the current
+  # project. This method is preferrable for accessing and querying for tags.
+  #
+  # @return [Array<Lifer::Tag>]
+  def tags = tag_manifest.to_a
+
+  # The tag manifest tracks the unique tags added to the project as they're added.
+  # The writer method for this instance variable is used internally by Lifer when
+  # adding new tags.
+  #
+  # @return [Set<Lifer::Tag>]
+  def tag_manifest = (@tag_manifest ||= Set.new)
+
   private
 
   attr_reader :config_file_location

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

@@ -56,10 +56,16 @@ class Lifer::Builder::HTML
     end
 
     # @private
-    # Each collection name is provided as a local variable. This allows you to
-    # make ERB files that contain loops like:
+    # Each collection and tag name is provided as a local variable. This allows
+    # you to make ERB files that contain loops like:
     #
-    #     <% my_collection_name.entries.each do |entry| %>
+    #     <% collections.my_collection_name.entries.each do |entry| %>
+    #       <%= entry.title %>
+    #     <% end %>
+    #
+    # or:
+    #
+    #     <% tags.my_tag_name.entries.each do |entry| %>
     #       <%= entry.title %>
     #     <% end %>
     #
@@ -75,18 +81,31 @@ class Lifer::Builder::HTML
           end
         end
 
-        collections = collection_context_class.new Lifer.collections.to_a
+        Lifer.tags.each do |tag|
+          binding.local_variable_set tag.name, tag
+
+          tag_context_class.define_method(tag.name) do
+            tag
+          end
+        end
+
+        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)
       }
     end
 
-    # @private
     def collection_context_class
       @collection_context_class ||= Class.new(Array) do end
     end
+
+    def tag_context_class
+      @tag_context_class ||= Class.new(Array) do end
+    end
   end
 end

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

@@ -28,7 +28,7 @@ module Lifer::Builder::HTML::FromLiquid::Drops
     # @return [Array<EntryDrop>]
     def entries
       @entries ||= lifer_collection.entries.map {
-        EntryDrop.new _1, collection: self
+        EntryDrop.new _1, collection: self, tags: _1.tags
       }
     end
 

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

@@ -18,7 +18,6 @@ module Lifer::Builder::HTML::FromLiquid::Drops
     #
     # @yield [CollectionDrop] All available collection drops.
     def each(&block)
-
       collections.each(&block)
     end
 

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

@@ -4,14 +4,17 @@ module Lifer::Builder::HTML::FromLiquid::Drops
   #
   # @example Usage
   #     <h1>{{ entry.title }}</h1>
-  #     <small>Published on <datetime>{{ entry.date }}</datetime></small>
+  #     <small>
+  #       Published on <datetime>{{ entry.published_at }}</datetime>
+  #     </small>
   #
   class EntryDrop < Liquid::Drop
     attr_accessor :lifer_entry, :collection
 
-    def initialize(lifer_entry, collection:)
+    def initialize(lifer_entry, collection:, tags:)
       @lifer_entry = lifer_entry
       @collection = collection
+      @tags = tags
     end
 
     # The entry author (or authors).
@@ -29,11 +32,6 @@ module Lifer::Builder::HTML::FromLiquid::Drops
     # @return [String]
     def content = (@content ||= lifer_entry.to_html)
 
-    # The entry date (as a string).
-    #
-    # @return [String]
-    def date = (@date ||= lifer_entry.date)
-
     # The entry frontmatter data.
     #
     # @return [FrontmatterDrop]
@@ -49,6 +47,11 @@ module Lifer::Builder::HTML::FromLiquid::Drops
     # @return [String] The entry permalink.
     def permalink = (@permalink ||= lifer_entry.permalink)
 
+    # The entry publication date (as a string).
+    #
+    # @return [String]
+    def published_at = (@published_at ||= lifer_entry.published_at)
+
     # The summary of the entry.
     #
     # @return [String] The summary of the entry.
@@ -58,5 +61,10 @@ module Lifer::Builder::HTML::FromLiquid::Drops
     #
     # @return [String] The entry title.
     def title = (@title ||= lifer_entry.title)
+
+    # The entry's last updated date (as a string).
+    #
+    # @return [String]
+    def updated_at = (@updated_at ||= lifer_entry.updated_at)
   end
 end

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

@@ -0,0 +1,42 @@
+module Lifer::Builder::HTML::FromLiquid::Drops
+  # This drop allows users to access Lifer tag information from within
+  # Liquid templates.
+  #
+  # @example Usage
+  #     {{ tag.name }}
+  #     {% for entries in tag.entries %}
+  #       {{ entry.title }}
+  #     {% endfor %}
+  #
+  class TagDrop < Liquid::Drop
+    attr_accessor :lifer_tag
+
+    def initialize(lifer_tag) = (@lifer_tag = lifer_tag)
+
+    # The tag name.
+    #
+    # @return [Symbol]
+    def name = (@name ||= lifer_tag.name)
+
+    # Gets all entries in a tag and converts them to entry drops that can
+    # be accessed in Liquid templates. Example:
+    #
+    #     {% for entry in tags..entries %}
+    #       {{ entry.title }}
+    #     {% endfor %}
+    #
+    # @return [Array<EntryDrop>]
+    def entries
+      @entries ||= lifer_tag.entries.map { |lifer_entry|
+        EntryDrop.new lifer_entry,
+          collection: CollectionDrop.new(lifer_entry.collection),
+          tags: lifer_entry.tags.map { TagDrop.new _1 }
+      }
+    end
+
+    # The tag's layout file path.
+    #
+    # @return [String] The path to the layout file.
+    def layout_file = (@lifer_tag.layout_file)
+  end
+end

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

@@ -0,0 +1,43 @@
+module Lifer::Builder::HTML::FromLiquid::Drops
+  # This drop allows users to iterate over their Lifer tags in Liquid
+  # templates.
+  #
+  # @example Usage
+  #     {% for tag in tags %}
+  #       {{ tag.name }}
+  #     {% endfor %}
+  #
+  #     {% for entry in tags.name-of-tag.entries %}
+  #       {{ entry.title }}
+  #     {% endfor %}
+  #
+  class TagsDrop < Liquid::Drop
+    attr_accessor :tags
+
+    def initialize
+      @tags = Lifer.tags.map { TagDrop.new _1 }
+    end
+
+    # Allow tags to be iterable in Liquid templates.
+    #
+    # @yield [CollectionDrop] All available collection drops.
+    def each(&block) = tags.each(&block)
+
+    # Allow tags to be rendered as an array in Liquid templates.
+    #
+    # @return [Array]
+    def to_a = @tags
+
+    # Dynamically define Liquid accessors based on the Lifer project's
+    # collection names.
+    #
+    # @example Get the "tagName" tag's entries.
+    #    {{ tags.tagName.entries }}
+    #
+    # @param arg [String] The name of a collection.
+    # @return [CollectionDrop, NilClass]
+    def liquid_method_missing(arg)
+      tags.detect { arg.to_s == _1.name.to_s }
+    end
+  end
+end

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

@@ -13,3 +13,5 @@ require_relative "drops/collections_drop"
 require_relative "drops/entry_drop"
 require_relative "drops/frontmatter_drop"
 require_relative "drops/settings_drop"
+require_relative "drops/tag_drop"
+require_relative "drops/tags_drop"

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

@@ -2,7 +2,7 @@
 # In many cases these utilities exist to be pseudo-compatible with Jekyll.
 #
 # @example A filter in a Liquid template.
-#     {{ entry.date | date_to_xmlschema }}
+#     {{ entry.published_at | date_to_xmlschema }}
 #
 module Lifer::Builder::HTML::FromLiquid::Filters
   # @!visibility private

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

@@ -5,7 +5,6 @@ require_relative "from_liquid/filters"
 require_relative "from_liquid/layout_tag"
 require_relative "from_liquid/liquid_env"
 
-
 class Lifer::Builder::HTML
   # If the HTML builder is given a Liquid template, it uses this class to parse
   # the Liquid into HTML. Lifer project metadata is provided as context. For
@@ -64,13 +63,16 @@ class Lifer::Builder::HTML
 
     def context
       collections = Drops::CollectionsDrop.new
+      tags = Drops::TagsDrop.new
       collection = collections
         .to_a
         .detect { _1.name.to_sym == entry.collection.name }
+      entry_tags = tags.to_a.select { entry.tags.include? _1 }
 
       {
         "collections" => collections,
-        "entry" => Drops::EntryDrop.new(entry, collection:),
+        "tags" => tags,
+        "entry" => Drops::EntryDrop.new(entry, collection:, tags: entry_tags),
         "parse_options" => parse_options,
         "render_options" => render_options,
         "settings" => Drops::SettingsDrop.new

data/lib/lifer/builder/rss.rb

@@ -65,8 +65,7 @@ class Lifer::Builder::RSS < Lifer::Builder
   # The name of the format type, as needed by `RSS::Maker`, used by default by
   # this feed builder.
   #
-  DEFAULT_MAkER_FORMAT_NAME = FORMATS[:rss]
-
+  DEFAULT_MAKER_FORMAT_NAME = FORMATS[:rss]
 
   self.name = :rss
   self.settings = [
@@ -96,7 +95,7 @@ class Lifer::Builder::RSS < Lifer::Builder
 
     return FORMATS[format] if FORMATS.keys.include? format
 
-    DEFAULT_MAkER_FORMAT_NAME
+    DEFAULT_MAKER_FORMAT_NAME
   end
 
   # Traverses and renders an RSS feed for feedable collection.
@@ -220,8 +219,21 @@ class Lifer::Builder::RSS < Lifer::Builder
       rss_feed_item.link = lifer_entry.permalink
       rss_feed_item.title = lifer_entry.title
       rss_feed_item.summary = lifer_entry.summary
-      rss_feed_item.updated = Time.now.to_s
-      rss_feed_item.content_encoded = lifer_entry.to_html
+
+      if feed_format(lifer_entry.collection) == "atom"
+        rss_feed_item.content.content = lifer_entry.to_html
+        rss_feed_item.published = lifer_entry.published_at
+
+        # Note: RSS does not provide a standard way to share last updated
+        # timestamps at all, while Atom does. This is the reason there is no
+        # equivalent call in the condition for RSS feeds.
+        #
+        rss_feed_item.updated =
+          lifer_entry.updated_at(fallback: lifer_entry.published_at)
+      else
+        rss_feed_item.content_encoded = lifer_entry.to_html
+        rss_feed_item.pubDate = lifer_entry.published_at.to_time.rfc2822
+      end
     end
   end
 

data/lib/lifer/collection.rb

@@ -57,9 +57,9 @@ class Lifer::Collection
         cached_entries_variable,
         case order
         when :latest
-          @entries_collection.sort_by { |entry| entry.date }.reverse
+          @entries_collection.sort_by { |entry| entry.published_at }.reverse
         when :oldest
-          @entries_collection.sort_by { |entry| entry.date }
+          @entries_collection.sort_by { |entry| entry.published_at }
         end
       )
   end

data/lib/lifer/entry/html.rb

@@ -7,21 +7,18 @@ 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.
+  # If there is no available metadata in the HTML file, we can extract a
+  # makeshift title from the permalink.
   #
-  # @return [Time] The publication date of the HTML entry.
-  def date = Lifer::Entry::DEFAULT_DATE
-
-  # Since HTML entries cannot provide metadata about themselves, we must extract
-  # a title from the permalink. Depending on the filename and URI strategy being
-  # used for the collection, it's possible that the extracted title would be
-  # "index", which is not very descriptive. If that's the case, we attempt to go
-  # up a directory to find a "non-index" title.
+  # Depending on the filename and URI strategy being used for the collection,
+  # it's possible that the extracted title would be "index", which is not very
+  # descriptive. If that's the case, we attempt to go up a directory to find a
+  # non-"index" title.
   #
-  # @return [String] The extracted title of the entry.
+  # @return [String] The given or extracted title of the entry.
   def title
+    return frontmatter[:title] if frontmatter[:title]
+
     candidate = File.basename(permalink, ".html")
 
     if candidate.include?("index") && !file.to_s.include?("index")
@@ -35,5 +32,5 @@ class Lifer::Entry::HTML < Lifer::Entry
   # doesn't do much here.
   #
   # @return [String]
-  def to_html = full_text
+  def to_html = body
 end

data/lib/lifer/entry/markdown.rb

@@ -14,78 +14,10 @@ require_relative "../utilities"
 # it may make sense to pull some of these methods into a separate module.
 #
 class Lifer::Entry::Markdown < Lifer::Entry
-  # If a filename contains a date, we should expect it to be in the following
-  # format.
-  #
-  FILENAME_DATE_FORMAT = /^(\d{4}-\d{1,2}-\d{1,2})-/
-
-  # We expect frontmatter to be provided in the following format.
-  #
-  FRONTMATTER_REGEX = /^---\n(.*)---\n/m
-
-  # We truncate anything that needs to be truncated (summaries, meta
-  # descriptions) at the following character count.
-  #
-  TRUNCATION_THRESHOLD = 120
-
   self.include_in_feeds = true
   self.input_extensions = ["md"]
   self.output_extension = :html
 
-  # 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.
-  #
-  # The return value here is likely an author's name. Whether that's a full
-  # name, a first name, or a handle is up to the end user.
-  #
-  # @return [Array<String>] An array of authors's names.
-  def authors
-    Array(frontmatter[:author] || frontmatter[:authors]).compact
-  end
-
-  # This method returns the full text of the entry, only removing the
-  # frontmatter. It should not parse anything other than frontmatter.
-  #
-  # @return [String] The body of the entry.
-  def body
-    return full_text.strip unless frontmatter?
-
-    full_text.gsub(FRONTMATTER_REGEX, "").strip
-  end
-
-  # Since Markdown files would only store dates as simple strings, it's nice to
-  # attempt to convert those into Ruby date or datetime objects.
-  #
-  # @return [Time] A Ruby representation of the date and time provided by the
-  #   entry frontmatter or filename.
-  def date
-    date_data = frontmatter[:date] || filename_date
-
-    case date_data
-    when Time then date_data
-    when String then DateTime.parse(date_data).to_time
-    else
-      Lifer::Message.log("entry.markdown.no_date_metadata", filename: file)
-      Lifer::Entry::DEFAULT_DATE
-    end
-  rescue ArgumentError => error
-    Lifer::Message.error("entry.markdown.date_error", filename: file, error:)
-    Lifer::Entry::DEFAULT_DATE
-  end
-
-  # Frontmatter is a widely supported YAML metadata block found at the top of
-  # Markdown files. We should attempt to parse Markdown entries for it.
-  #
-  # @return [Hash] A hash representation of the entry frontmatter.
-  def frontmatter
-    return {} unless frontmatter?
-
-    Lifer::Utilities.symbolize_keys(
-      YAML.load(full_text[FRONTMATTER_REGEX, 1], permitted_classes: [Time])
-    )
-  end
-
   # 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
@@ -96,7 +28,7 @@ class Lifer::Entry::Markdown < Lifer::Entry
   #
   # @return [String] A summary of the entry.
   def summary
-    return frontmatter[:summary] if frontmatter[:summary]
+    return super if super
 
     return if first_paragraph.nil?
     return first_paragraph if first_paragraph.length <= TRUNCATION_THRESHOLD
@@ -130,11 +62,17 @@ class Lifer::Entry::Markdown < Lifer::Entry
 
   private
 
-  # @private
-  def filename_date
-    return unless file && File.basename(file).match?(FILENAME_DATE_FORMAT)
-
-    File.basename(file).match(FILENAME_DATE_FORMAT)[1]
+  # 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.
+  #
+  # @return [Array<String>] An array of candidate tag names.
+  def candidate_tag_names
+    case frontmatter[:tags]
+    when Array then frontmatter[:tags].map(&:to_s)
+    when String then frontmatter[:tags].split(TAG_DELIMITER_REGEX)
+    else []
+    end.uniq
   end
 
   # Using Kramdown we can detect the first paragraph of the entry.
@@ -149,11 +87,6 @@ class Lifer::Entry::Markdown < Lifer::Entry
       )
   end
 
-  # @private
-  def frontmatter?
-    full_text && full_text.match?(FRONTMATTER_REGEX)
-  end
-
   # @private
   def kramdown_paragraph_text(kramdown_element)
     return if kramdown_element.nil?

data/lib/lifer/entry/txt.rb

@@ -7,21 +7,18 @@ 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.
+  # If there is no available metadata in the text file, we can extract a
+  # makeshift title from the permalink.
   #
-  # @return [Time] The publication date of the HTML entry.
-  def date = Lifer::Entry::DEFAULT_DATE
-
-  # Since text  entries cannot provide metadata about themselves, we must extract
-  # a title from the permalink. Depending on the filename and URI strategy being
-  # used for the collection, it's possible that the extracted title would be
-  # "index", which is not very descriptive. If that's the case, we attempt to go
-  # up a directory to find a "non-index" title.
+  # Depending on the filename and URI strategy being used for the collection,
+  # it's possible that the extracted title would be "index", which is not very
+  # descriptive. If that's the case, we attempt to go up a directory to find a
+  # non-"index" title.
   #
-  # @return [String] The extracted title of the entry.
+  # @return [String] The given or extracted title of the entry.
   def title
+    return frontmatter[:title] if frontmatter[:title]
+
     candidate = File.basename(permalink, ".txt")
 
     if candidate.include?("index") && !file.to_s.include?("index")
@@ -37,5 +34,5 @@ class Lifer::Entry::TXT < Lifer::Entry
   # @fixme Maybe the `#to_html` methods should be renamed, then?
   #
   # @return [String] The output HTML (not actually HTML).
-  def to_html = full_text
+  def to_html = body
 end

data/lib/lifer/entry.rb

@@ -1,166 +1,331 @@
 require "digest/sha1"
 
-# An entry is a Lifer file that will be built into the output directory.
-# There are more than one subclass of entry: Markdown entries are the most
-# traditional, but HTML and text files are also very valid entries.
-#
-# This class provides a baseline of the functionality that all entry subclasses
-# should implement. It also provides the entry generator for *all* entry
-# subclasses.
-#
-# @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?
-#
-class Lifer::Entry
-  class << self
-    attr_accessor :include_in_feeds
-    attr_accessor :input_extensions
-    attr_accessor :output_extension
-  end
+module Lifer
+  # An entry is a Lifer file that will be built into the output directory.
+  # There are more than one subclass of entry: Markdown entries are the most
+  # traditional, but HTML and text files are also very valid entries.
+  #
+  # This class provides a baseline of the functionality that all entry
+  # subclasses should implement. It also provides the entry generator for
+  # *all* entry subclasses.
+  #
+  # @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?
+  #
+  class Entry
+    class << self
+      attr_accessor :include_in_feeds
+      attr_accessor :input_extensions
+      attr_accessor :output_extension
+    end
 
-  self.include_in_feeds = false
-  self.input_extensions = []
-  self.output_extension = nil
+    self.include_in_feeds = false
+    self.input_extensions = []
+    self.output_extension = nil
 
-  require_relative "entry/html"
-  require_relative "entry/markdown"
-  require_relative "entry/txt"
+    require_relative "entry/html"
+    require_relative "entry/markdown"
+    require_relative "entry/txt"
 
-  # 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.
-  #
-  DEFAULT_DATE = Time.new(1900, 01, 01, 0, 0, 0, "+00:00")
+    # 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.
+    #
+    DEFAULT_DATE = Time.new(1900, 01, 01, 0, 0, 0, "+00:00")
+
+    # If a filename contains a date, we should expect it to be in the following
+    # format.
+    #
+    FILENAME_DATE_FORMAT = /^(\d{4}-\d{1,2}-\d{1,2})-/
+
+    # We expect frontmatter to be provided in the following format.
+    #
+    FRONTMATTER_REGEX = /^---\n(.*)---\n/m
 
-  attr_reader :file, :collection
+    # If tags are represented in YAML frontmatter as a string, they're split on
+    # commas and/or spaces.
+    #
+    TAG_DELIMITER_REGEX = /[,\s]+/
 
-  class << self
-    # The entrypoint for generating entry objects. We should never end up with
-    # `Lifer::Entry` records: only subclasses.
+    # We truncate anything that needs to be truncated (summaries, meta
+    # descriptions) at the following character count.
     #
-    # @param file [String] The absolute filename of an entry file.
-    # @param collection [Lifer::Collection] The collection for the entry.
-    # @return [Lifer::Entry::HTML, Lifer::Entry::Markdown]
-    def generate(file:, collection:)
-      error!(file) unless File.exist?(file)
+    TRUNCATION_THRESHOLD = 120
+
+    attr_reader :file, :collection
+
+    class << self
+      # The entrypoint for generating entry objects. We should never end up with
+      # `Lifer::Entry` records: only subclasses.
+      #
+      # @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:)
+        error!(file) unless File.exist?(file)
+
+        if (new_entry = subclass_for(file)&.new(file:, collection:))
+          Lifer.entry_manifest << new_entry
+          new_entry.tags
+        end
+
+        new_entry
+      end
+
+      # Whenever an entry is generated it should be added to the entry manifest.
+      # This lets us get a list of all generated entries.
+      #
+      # @return [Array<Lifer::Entry>] A list of all entries that currently exist.
+      def manifest
+        return Lifer.entry_manifest if self == Lifer::Entry
+
+        Lifer.entry_manifest.select { |entry| entry.class == self }
+      end
+
+      # Checks whether the given filename is supported entry type (using only its
+      # file extension).
+      #
+      # @param filename [String] The absolute filename to an entry.
+      # @param file_extensions [Array<String>] An array of file extensions to
+      #   check against.
+      # @return [Boolean]
+      def supported?(filename, file_extensions= supported_file_extensions)
+        file_extensions.any? { |ext| filename.end_with? ext }
+      end
 
-      if (new_entry = subclass_for(file)&.new(file:, collection:))
-        Lifer.entry_manifest << new_entry
+      private
+
+      def supported_file_extensions
+        @supported_file_extensions ||= subclasses.flat_map(&:input_extensions)
+      end
+
+      # @private
+      # Retrieve the entry subclass based on the current filename.
+      #
+      # @param filename [String] The current entry's filename.
+      # @return [Class] The entry subclass for the current entry.
+      def subclass_for(filename)
+        Lifer::Entry.subclasses.detect { |klass|
+          klass.input_extensions.any? { |ext| filename.end_with? ext }
+        }
+      end
+
+      # @private
+      def error!(file)
+        raise StandardError, I18n.t("entry.not_found", file:)
       end
-      new_entry
     end
 
-    # Whenever an entry is generated it should be added to the entry manifest.
-    # This lets us get a list of all generated entries.
+    # When a new entry is initialized we expect the file to already exist, and
+    # we expect to know which `Lifer::Collection` it belongs to.
     #
-    # @return [Array<Lifer::Entry>] A list of all entries that currently exist.
-    def manifest
-      return Lifer.entry_manifest if self == Lifer::Entry
+    # @param file [String] An absolute path to a file.
+    # @param collection [Lifer::Collection] A collection.
+    # @return [Lifer::Entry]
+    def initialize(file:, collection:)
+      @file = Pathname file
+      @collection = collection
+    end
 
-      Lifer.entry_manifest.select { |entry| entry.class == self }
+    # 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.
+    #
+    # The return value here is likely an author's name. Whether that's a full
+    # name, a first name, or a handle is up to the end user.
+    #
+    # @return [Array<String>] An array of authors's names.
+    def authors
+      Array(frontmatter[:author] || frontmatter[:authors]).compact
     end
 
-    # Checks whether the given filename is supported entry type (using only its
-    # file extension).
+    # This method returns the full text of the entry, only removing the
+    # frontmatter. It should not parse anything other than frontmatter.
     #
-    # @param filename [String] The absolute filename to an entry.
-    # @param file_extensions [Array<String>] An array of file extensions to
-    #   check against.
-    # @return [Boolean]
-    def supported?(filename, file_extensions= supported_file_extensions)
-      file_extensions.any? { |ext| filename.end_with? ext }
+    # @return [String] The body of the entry.
+    def body
+      return full_text.strip unless frontmatter?
+
+      full_text.gsub(FRONTMATTER_REGEX, "").strip
     end
 
-    private
+    def feedable?
+      if (setting = self.class.include_in_feeds).nil?
+        raise NotImplementedError,
+          I18n.t("entry.feedable_error", entry_class: self.class)
+      end
 
-    def supported_file_extensions
-      @supported_file_extensions ||= subclasses.flat_map(&:input_extensions)
+      setting
     end
 
-    # @private
-    # Retrieve the entry subclass based on the current filename.
+    # Frontmatter is a widely supported YAML metadata block found at the top of
+    # text--often Markdown--files. We attempt to parse all entries for
+    # frontmatter.
     #
-    # @param filename [String] The current entry's filename.
-    # @return [Class] The entry subclass for the current entry.
-    def subclass_for(filename)
-      Lifer::Entry.subclasses.detect { |klass|
-        klass.input_extensions.any? { |ext| filename.end_with? ext }
-      }
+    # @return [Hash] A hash representation of the entry frontmatter.
+    def frontmatter
+      return {} unless frontmatter?
+
+      Lifer::Utilities.symbolize_keys(
+        YAML.load(full_text[FRONTMATTER_REGEX, 1], permitted_classes: [Time])
+      )
     end
 
-    # @private
-    def error!(file)
-      raise StandardError, I18n.t("entry.not_found", file:)
+    # The full text of the entry.
+    #
+    # @return [String]
+    def full_text
+      @full_text ||= File.readlines(file).join if file
     end
-  end
 
-  # When a new Markdown entry is initialized we expect the file to already
-  # exist, and we expect to know which `Lifer::Collection` it belongs to.
-  #
-  # @param file [String] An absolute path to a file.
-  # @param collection [Lifer::Collection] A collection.
-  # @return [Lifer::Entry]
-  def initialize(file:, collection:)
-    @file = Pathname file
-    @collection = collection
-  end
+    # Using the current Lifer configuration, we can calculate the expected
+    # permalink for the entry. For example:
+    #
+    #    https://example.com/index.html
+    #    https://example.com/blog/my-trip-to-toronto.html
+    #
+    # This would be useful for indexes and feeds and so on.
+    #
+    # @return [String] A permalink to the current entry.
+    def permalink(host: Lifer.setting(:global, :host))
+      cached_permalink_variable =
+        "@entry_permalink_" + Digest::SHA1.hexdigest(host)
 
-  def feedable?
-    if (setting = self.class.include_in_feeds).nil?
-      raise NotImplementedError,
-        I18n.t("entry.feedable_error", entry_class: self.class)
+      instance_variable_get(cached_permalink_variable) ||
+        instance_variable_set(
+          cached_permalink_variable,
+          File.join(
+            host,
+            Lifer::URIStrategy.find(collection.setting :uri_strategy)
+              .new(root: Lifer.root)
+              .output_file(self)
+          )
+        )
     end
 
-    setting
-  end
+    # The expected, absolute URI path to the entry. For example:
+    #
+    #    /index.html
+    #    /blog/my-trip-to-toronto.html
+    #
+    # @return [String] The absolute URI path to the entry.
+    def path = permalink(host: "/")
 
-  # The full text of the entry.
-  #
-  # @return [String]
-  def full_text
-    @full_text ||= File.readlines(file).join if file
-  end
+    # The entry's publication date. The published date can be inferred in a few
+    # ways. The priority is:
+    #
+    #    1. the frontmatter's `published_at` field
+    #    2. the frontmatter's `published` field
+    #    3. the frontamtter's `date` field
+    #    4. The date in the filename.
+    #
+    # Since text files would only store dates as simple strings, it's nice to
+    # attempt to convert those into Ruby date or datetime objects.
+    #
+    # @return [Time] A Ruby representation of the date and time provided by the
+    #   entry frontmatter or filename.
+    def published_at
+      date_for frontmatter[:published_at],
+        frontmatter[:published],
+        frontmatter[:date],
+        filename_date,
+        missing_metadata_translation_key: "entry.no_published_at_metadata"
+    end
 
-  # Using the current Lifer configuration, we can calculate the expected
-  # permalink for the entry. For example:
-  #
-  #    https://example.com/index.html
-  #    https://example.com/blog/my-trip-to-toronto.html
-  #
-  # This would be useful for indexes and feeds and so on.
-  #
-  # @return [String] A permalink to the current entry.
-  def permalink(host: Lifer.setting(:global, :host))
-    cached_permalink_variable =
-      "@entry_permalink_" + Digest::SHA1.hexdigest(host)
-
-    instance_variable_get(cached_permalink_variable) ||
-      instance_variable_set(
-        cached_permalink_variable,
-        File.join(
-          host,
-          Lifer::URIStrategy.find(collection.setting :uri_strategy)
-            .new(root: Lifer.root)
-            .output_file(self)
-        )
-      )
-  end
+    # If given a summary in the frontmatter of the entry, we can use this to
+    # provide a summary.
+    #
+    # Since subclasses may have more sophisticated access to the document, they
+    # may override this method with their own distinct implementations.
+    ##
+    # @return [String] A summary of the entry.
+    def summary
+      return frontmatter[:summary] if frontmatter[:summary]
+    end
 
-  # The expected, absolute URI path to the entry. For example:
-  #
-  #    /index.html
-  #    /blog/my-trip-to-toronto.html
-  #
-  # @return [String] The absolute URI path to the entry.
-  def path = permalink(host: "/")
+    # Locates and returns all tags defined in the entry.
+    #
+    # @return [Array<Lifer::Tag>] The entry's tags.
+    def tags
+      @tags ||= candidate_tag_names
+        .map { Lifer::Tag.build_or_update(name: _1, entries: [self]) }
+    end
 
-  def title
-    raise NotImplementedError, I18n.t("shared.not_implemented_method")
-  end
+    # Returns the title of the entry. Every entry subclass must implement this
+    # method so that builders have access to *some* kind of title for each entry.
+    #
+    # @return [String]
+    def title
+      raise NotImplementedError, I18n.t("shared.not_implemented_method")
+    end
+
+    def to_html
+      raise NotImplementedError, I18n.t("shared.not_implemented_method")
+    end
 
-  def to_html
-    raise NotImplementedError, I18n.t("shared.not_implemented_method")
+    # The entry's last updated date. In the frontmatter, the last updated date
+    # can be specified using one of two fields. In priority order:
+    #
+    #    1. the `updated_at` field
+    #    2. the `updated` field
+    #
+    # The developer could set a fallback value as a fallback. For example, when
+    # building RSS feeds one might want the value of `#published_at` if there is
+    # no last updated date.
+    #
+    # @param fallback [Time, String, NilClass] Provide datetime data, a string
+    #   that parses to a datetime object, or nil.
+    # @return [Time] A Ruby representation of the date and time provided by the
+    #   entry frontmatter.
+    def updated_at(fallback: nil)
+      date_for frontmatter[:updated_at],
+        frontmatter[:updated],
+        default_date: fallback
+    end
+
+    private
+
+    # 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.
+    #
+    # @return [Array<String>] An array of candidate tag names.
+    def candidate_tag_names
+      case frontmatter[:tags]
+      when Array then frontmatter[:tags].map(&:to_s)
+      when String then frontmatter[:tags].split(TAG_DELIMITER_REGEX)
+      else []
+      end.uniq
+    end
+
+    def date_for(
+      *candidate_date_fields,
+      default_date: Lifer::Entry::DEFAULT_DATE,
+      missing_metadata_translation_key: nil
+    )
+      date_data = candidate_date_fields.detect(&:itself)
+
+      case date_data
+      when Time then date_data
+      when String then DateTime.parse(date_data).to_time
+      else
+        if (translation_string = missing_metadata_translation_key)
+          Lifer::Message.log(translation_string, filename: file)
+        end
+        default_date
+      end
+    rescue ArgumentError => error
+      Lifer::Message.error("entry.date_error", filename: file, error:)
+      default_date
+    end
+
+    def filename_date
+      return unless file && File.basename(file).match?(FILENAME_DATE_FORMAT)
+
+      File.basename(file).match(FILENAME_DATE_FORMAT)[1]
+    end
+
+    def frontmatter? = (full_text && full_text.match?(FRONTMATTER_REGEX))
   end
 end
-

data/lib/lifer/tag.rb

@@ -0,0 +1,53 @@
+module Lifer
+  # A tag is a way to categorize entries. You've likely encountered tags in
+  # other software before. In Lifer, tags are sort of the inverse of
+  # collections. It's a nice way to associate entries across many collections.
+  #
+  # Because tags are used to link entries, we definitely do not want duplicate
+  # tags. So the only way to build or retrieve tags is via the
+  # `.build_or_update` class method, which helps us responsibly manage the
+  # global tag manifest.
+  #
+  class Tag
+    class << self
+      # Builds or updates a Lifer tag. On update, its list of entries gets
+      # freshened.
+      #
+      # @param name [String] The name of the tag.
+      # @param entries [Array<Lifer::Entry>] A list of entries that should be
+      #   associated with the tag. This parameter is not a true writer, in that
+      #   if the tag already exists, old entry associations won't be removed--
+      #   only appended to.
+      # @return [Lifer:Tag] The new or updated tag.
+      def build_or_update(name:, entries: [])
+        update(name:, entries:) || build(name:, entries:)
+      end
+
+      private
+
+      def build(name:, entries:)
+        if (new_tag = new(name:, entries:))
+          Lifer.tag_manifest << new_tag
+        end
+        new_tag || false
+      end
+
+      def update(name:, entries:)
+        if (tag = Lifer.tags.detect { _1.name == name })
+          tag.instance_variable_set :@entries,
+            (tag.instance_variable_get(:@entries) | entries)
+        end
+        tag || false
+      end
+    end
+
+    attr_accessor :name
+
+    attr_reader :entries
+
+    def initialize(name:, entries:)
+      @name = name
+      @entries = entries
+    end
+  end
+end

data/lib/lifer/utilities.rb

@@ -76,7 +76,10 @@ module Lifer::Utilities
     # @raise [Exception] Any exception thrown by a child process.
     # @return [Array] The mapped results of the operation.
     def parallelized(collection, &block)
-      results = Parallel.map(collection) do |collection_item|
+      options = {}
+      options[:in_threads] = 0 if Lifer.parallelism_disabled?
+
+      results = Parallel.map(collection, **options) do |collection_item|
         begin
           yield collection_item
         rescue => error

data/lib/lifer/version.rb

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

data/lib/lifer.rb

@@ -96,6 +96,16 @@ module Lifer
     #   project would be built to.
     def output_directory = brain.output_directory
 
+    # Returns false if the Lifer project will be built with parallelism. This
+    # should return false almost always--unless you've explicitly set the
+    # `LIFER_UNPARALLELIZED` environment variable before running the program.
+    #
+    # This method is used internally by Lifer to determine whether features that
+    # would normally run in parallel should *not* run in parallel for some reason.
+    #
+    # @return [boolean] Returns whether parallelism is disabled.
+    def parallelism_disabled? = ENV["LIFER_UNPARALLELIZED"].is_a?(String)
+
     # Register new settings so that they are "safe" and can be read from a Lifer
     # configuration file. Unregistered settings are ignored.
     #
@@ -141,6 +151,17 @@ module Lifer
     #
     # @return [Hash] The `Lifer::Config#settings`.
     def settings = brain.config.settings
+
+    # All of the tags represented in Lifer entries for the current project.
+    #
+    # @return [Array<Lifer::Tag>] The complete list of tags.
+    def tags = brain.tags
+
+    # A set of all tags added to the project. Prefer using the `#tags` method
+    # for tag queries.
+    #
+    # @return [Set<Lifer::Tag>] The complete set of tags.
+    def tag_manifest = brain.tag_manifest
   end
 end
 
@@ -158,4 +179,5 @@ require_relative "lifer/builder"
 require_relative "lifer/collection"
 require_relative "lifer/entry"
 require_relative "lifer/message"
+require_relative "lifer/tag"
 require_relative "lifer/uri_strategy"

data/lifer.gemspec

@@ -17,9 +17,9 @@ Gem::Specification.new do |spec|
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
   spec.metadata["homepage_uri"] =
-    "%s/blob/%s/README.md" % [spec.homepage, Lifer::VERSION]
+    "%s/blob/%s/README.md" % [spec.homepage, "v#{Lifer::VERSION}"]
   spec.metadata["source_code_uri"] =
-    "%s/tree/%s" % [spec.homepage, Lifer::VERSION]
+    "%s/tree/%s" % [spec.homepage, "v#{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

data/locales/en.yml

@@ -30,11 +30,10 @@ en:
       content_type_not_implemented: no content type defined for files like %{path} yet
       four_oh_four: 404 Not Found
   entry:
+    date_error: "[%{filename}]: %{error}"
     feedable_error: >
       please set `%{entry_class}.include_in_feeds` to true or false
-    markdown:
-      date_error: "[%{filename}]: %{error}"
-      no_date_metadata: "[%{filename}]: no date metadata"
+    no_published_at_metadata: "[%{filename}]: no `published_at` metadata"
     not_found: >
       file "%{file}" does not exist
   config:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lifer
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - benjamin wil
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-03 00:00:00.000000000 Z
+date: 2025-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
@@ -167,6 +167,8 @@ files:
 - lib/lifer/builder/html/from_liquid/drops/entry_drop.rb
 - lib/lifer/builder/html/from_liquid/drops/frontmatter_drop.rb
 - lib/lifer/builder/html/from_liquid/drops/settings_drop.rb
+- lib/lifer/builder/html/from_liquid/drops/tag_drop.rb
+- lib/lifer/builder/html/from_liquid/drops/tags_drop.rb
 - lib/lifer/builder/html/from_liquid/filters.rb
 - lib/lifer/builder/html/from_liquid/layout_tag.rb
 - lib/lifer/builder/html/from_liquid/liquid_env.rb
@@ -188,6 +190,7 @@ files:
 - lib/lifer/selection/included_in_feeds.rb
 - lib/lifer/shared.rb
 - lib/lifer/shared/finder_methods.rb
+- lib/lifer/tag.rb
 - lib/lifer/templates/cli.txt.erb
 - lib/lifer/templates/config.yaml
 - lib/lifer/templates/its-a-living.png
@@ -207,8 +210,8 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  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
+  homepage_uri: https://github.com/benjaminwil/lifer/blob/v0.9.0/README.md
+  source_code_uri: https://github.com/benjaminwil/lifer/tree/v0.9.0
   changelog_uri: https://github.com/benjaminwil/lifer/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []