lifer 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39e8d5c991a955d4c09740207671d49716b6ef42168b250fbe301c6a443785d5
-  data.tar.gz: 73e4ea67bc8e9af6f1503782c53c334c5d59f31a2afd351312eb8365b9b42af7
+  metadata.gz: ea41a2cd1a058f5a103121b6b7641ce5857ec74300ecad4bb36ec33578170650
+  data.tar.gz: f752dc7498a0457945d895fc591eefc7a27a296e01a5b547264a13fd8113c3b5
 SHA512:
-  metadata.gz: eacb4bd82e882758d88e9ffc0de30de8cb9213f35454856a2bed3f487bb8dc568afdb07ac22d6c269ac1b4c9418a18789dcd124193de009456243a2eeedc6415
-  data.tar.gz: a8dd94d4c24932faae325461a4530c7f931d7ee7315353dc31ca42dac61c325ca91edd5f4f990e0710f4c18d4fbb9b020f51c1f13d8a02012d7c7f4918f5f88e
+  metadata.gz: 4665579521538df261c0839f6c1a7ee6b24362ca75c03cc6d8fbf42dfffa028ad0bc39c1fe01ef2407459cb1be6bdf9d08e60cd5abacd1e233b0819bbcab6186
+  data.tar.gz: e1bfbd9fa63bd2de10022f2b5810cfcf518acc5112f51bb843c19c936bc269436807a606c335ab90693bafac53569315b0bfcbe245b9c8570a56ff6ab60af6f0

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 ## Next
 
+## 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
+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.8.0)
       i18n (< 2)
       kramdown (~> 2.4)
       liquid (~> 5.6, < 6)

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.
@@ -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)
@@ -140,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
@@ -160,12 +172,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_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

@@ -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 %}
@@ -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

@@ -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 %}
@@ -17,7 +18,6 @@ module Lifer::Builder::HTML::FromLiquid::Drops
     #
     # @yield [CollectionDrop] All available collection drops.
     def each(&block)
-
       collections.each(&block)
     end
 
@@ -27,8 +27,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,17 +2,17 @@ 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>
   #
   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).

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/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

@@ -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/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/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?