lifer 0.9.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b6414082e8f6f1d9b18034f2f227890b85ac73b22ab50c25cb2e350812c1a90
-  data.tar.gz: 5891afc57d102fd67422bf581edc4de839b05efbe10d104529a817391c0e7cad
+  metadata.gz: ae7d44054aac227a4d75940cf8c6d30b46ba403780f5d8583d0db22dfd8cf36e
+  data.tar.gz: 7c8ac4e684afa95e23f22dc1b6ad0472391c3fc946a6b7bbbdf9acfbf46ac31d
 SHA512:
-  metadata.gz: 7adb1041c558a2d60ef525bf1d12af4dd3d587a26f8ae0ef4e2f4c8fb9e04e14c648cf4bd72717aba143e747ccabe970ec1c859cd0c69b5259847887c0f99361
-  data.tar.gz: a9ec79fce82554f69ba1634ce414b7b63014c8545f8f8c5a6201c194d375d57d09a36128db4f6b242c279bfe0fe419f3b333034268415379c1b9138d372d352f
+  metadata.gz: 464566f240f05e2c5e199582555ccecd9bc6449ad477d53adb24905d76e07b9f93c13d050f69cd6c5923f9f9434edca1d14b4d01d674c5b4148bb5d9c85723df
+  data.tar.gz: 270f4d8c20bc24b180ae474a6d62037b2f2347a4d9e25f7a4af207d0e85d6df66fec0f92a82f57248e05ac34966ba69ff542a30c9e36d4f90e99fe41a46eeba6

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 ## Next
 
+## v0.10.1
+
+This release resolves a bug with `Entry#summary`. When I originally implemented
+summaries as first paragraphs, I didn't realize that using the Kramdown
+representation of the document would result in special characters being
+transformed badly:
+
+    In the ldquorealmrdquo where dreams dance
+
+This change ensures that we don't end up with trash like that, or other HTML
+trash.
+
+The summary is meant to be ideal for things like `<meta>` description tags,
+which should only contain plain text.
+
+
+## v0.10.0
+
+This release lets all layout files (either Liquid or ERB files) provide a
+reference to parent, or "root", layout files that should wrap the via
+frontmatter.
+
+Previously, we did this for Liquid layouts using the custom `layout` tag. But
+because there was no equivalent tag for ERB files, I realized it would be less
+work to just provide the value via frontmatter. The same way for every type of
+layout file.
+
+End users (just me?) must update their Lifer project Liquid layouts accordingly:
+
+```diff
+- {% layout "layouts/root_layout.html.liquid" %}
++ ---
++ layout: layouts/root_layout.html.liquid
++ ---
+
+  Layout content.
+```
+
 ## v0.9.0
 
 Atom feeds now support entries with both `#published_at` and `#updated_at`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lifer (0.9.0)
+    lifer (0.10.1)
       i18n (< 2)
       kramdown (~> 2.4)
       liquid (~> 5.6, < 6)
@@ -32,9 +32,9 @@ GEM
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.5.1)
-    ffi (1.17.1-arm64-darwin)
-    ffi (1.17.1-x86_64-darwin)
-    ffi (1.17.1-x86_64-linux-gnu)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86_64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     io-console (0.7.2)
@@ -44,7 +44,7 @@ GEM
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     language_server-protocol (3.17.0.3)
-    liquid (5.8.2)
+    liquid (5.8.6)
       bigdecimal
       strscan (>= 3.1.1)
     listen (3.9.0)
@@ -107,7 +107,7 @@ GEM
       sorbet-runtime (>= 0.5.10782)
     sorbet-runtime (0.5.11558)
     stringio (3.1.1)
-    strscan (3.1.2)
+    strscan (3.1.5)
     xpath (3.2.0)
       nokogiri (~> 1.8)
     yard (0.9.37)

data/README.md

@@ -107,6 +107,10 @@ Then, build and push the gem to RubyGems:
     $ gem build
     $ gem push lifer-<new_version_without_the_v_prefix>.gem
 
+And ensure that the release commit(s) are on the `main` branch:
+
+    $ git push origin main
+
 ## Contributing
 
 I'm not currently accepting unsolicited contributions to Lifer. I'm still

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

@@ -0,0 +1,66 @@
+class Lifer::Builder
+  class HTML
+    # A base class for all HTML builder adapters. The methods provided by this
+    # class are either required or reusable by builder subclasses. See the
+    # committed HTML builder adapter classes for example implementations.
+    class FromAny
+      class << self
+        # Build and render an entry.
+        #
+        # @param entry [Lifer::Entry] The entry to be rendered.
+        # @return [String] The rendered entry.
+        def build(entry:)
+          new(entry: entry).render
+        end
+      end
+
+      # The base class does not provide a render method, but any subclass
+      # should be expected to.
+      #
+      # @raise [NotImplementedError]
+      def render
+        raise NotImplementedError,
+          "subclasses must implement a custom `#render` method"
+      end
+
+      private
+
+      # The frontmatter provided by the layout file.
+      #
+      # @return [Hash] The frontmatter represented as a hash.
+      def frontmatter
+        return {} unless frontmatter?
+
+        Lifer::Utilities.symbolize_keys(
+          YAML.load layout_file_contents(raw: true)[Lifer::FRONTMATTER_REGEX, 1],
+            permitted_classes: [Time]
+        )
+      end
+
+      # Checks whether frontmatter is present in the layout file.
+      #
+      # @return [boolean]
+      def frontmatter?
+        @frontmatter ||=
+          layout_file_contents(raw: true).match?(Lifer::FRONTMATTER_REGEX)
+      end
+
+      # The contents of the layout file.
+      #
+      # @param raw [boolean] Whether to include or exclude frontmatter from
+      #   the contents.
+      # @return [String] The contents of the layout file.
+      def layout_file_contents(raw: false)
+        cache_variable = "@layout_file_contents_#{raw}"
+        cached_value = instance_variable_get cache_variable
+
+        return cached_value if cached_value
+
+        contents = File.read layout_file
+        contents = contents.gsub(Lifer::FRONTMATTER_REGEX, "") unless raw
+
+        instance_variable_set cache_variable, contents
+      end
+    end
+  end
+end

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

@@ -23,23 +23,21 @@ class Lifer::Builder::HTML
   #       </body>
   #     </html>
   #
-  class FromERB
-    class << self
-      # Build and render an entry.
-      #
-      # @param entry [Lifer::Entry] The entry to be rendered.
-      # @return [String] The rendered entry.
-      def build(entry:)
-        new(entry: entry).render
-      end
-    end
-
+  class FromERB < FromAny
     # Reads the entry as ERB, given our renderer context (see the documentation
     # for `#build_binding_context`) and renders the production-ready entry.
     #
     # @return [String] The rendered entry.
     def render
-      ERB.new(File.read layout_file).result context
+      document = ERB.new(layout_file_contents).result context
+
+      return document unless (relative_layout_path = frontmatter[:layout])
+
+      document_binding = binding.tap { |binding|
+        binding.local_variable_set :content, document
+      }
+      layout_path = "%s/%s" % [Lifer.root, relative_layout_path]
+      ERB.new(File.read layout_path).result(document_binding)
     end
 
     private

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

@@ -22,8 +22,6 @@ class Lifer::Builder::HTML::FromLiquid
           Liquid::LocalFileSystem.new(Lifer.root, "%s.html.liquid")
 
         environment.register_filter Lifer::Builder::HTML::FromLiquid::Filters
-        environment.register_tag "layout",
-          Lifer::Builder::HTML::FromLiquid::LayoutTag
       end
     end
   end

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

@@ -1,10 +1,5 @@
 require "liquid"
 
-require_relative "from_liquid/drops"
-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
@@ -28,16 +23,10 @@ class Lifer::Builder::HTML
   #       </body>
   #     </html>
   #
-  class FromLiquid
-    class << self
-      # Render and build a Lifer entry.
-      #
-      # @param entry [Lifer::Entry] The entry to render.
-      # @return [String] The rendered entry, ready for output.
-      def build(entry:) = new(entry:).render
-    end
-
-    attr_accessor :entry, :layout_file
+  class FromLiquid < FromAny
+    require_relative "from_liquid/drops"
+    require_relative "from_liquid/filters"
+    require_relative "from_liquid/liquid_env"
 
     # Reads the entry as Liquid, given our document context, and renders
     # an entry.
@@ -49,13 +38,23 @@ class Lifer::Builder::HTML
           .parse(entry.to_html, **parse_options)
           .render(context, **render_options)
       )
+      document = Liquid::Template
+        .parse(layout_file_contents, **parse_options)
+        .render(document_context, **render_options)
+
+      return document unless (relative_layout_path = frontmatter[:layout])
+
+      layout_path = "%s/%s" % [Lifer.root, relative_layout_path]
+      document_context = context.merge! "content" => document
       Liquid::Template
-        .parse(layout, **parse_options)
+        .parse(File.read layout_path, **parse_options)
         .render(document_context, **render_options)
     end
 
     private
 
+    attr_accessor :entry, :layout_file
+
     def initialize(entry:)
       @entry = entry
       @layout_file = entry.collection.layout_file
@@ -79,19 +78,6 @@ class Lifer::Builder::HTML
       }
     end
 
-    # @private
-    # It's possible for the provided layout to request a parent layout, which
-    # makes this method a bit complicated.
-    #
-    # @return [String] A Liquid layout document, ready for parsing.
-    def layout
-      contents = File.read layout_file
-
-      return contents unless contents.match?(/\{%\s*#{LayoutTag::NAME}.*%\}/)
-
-      contents + "\n{% #{LayoutTag::ENDNAME} %}"
-    end
-
     def liquid_environment = (@liquid_environment ||= LiquidEnv.global)
 
     def parse_options
@@ -103,6 +89,7 @@ class Lifer::Builder::HTML
 
     def render_options
       {
+        registers: {file_system: liquid_environment.file_system},
         strict_variables: true,
         strict_filters: true
       }

data/lib/lifer/builder/html.rb

@@ -33,6 +33,7 @@ require "fileutils"
 class Lifer::Builder::HTML < Lifer::Builder
   self.name = :html
 
+  require_relative "html/from_any"
   require_relative "html/from_erb"
   require_relative "html/from_liquid"
 

data/lib/lifer/entry/markdown.rb

@@ -30,14 +30,16 @@ class Lifer::Entry::Markdown < Lifer::Entry
   def summary
     return super if super
 
-    return if first_paragraph.nil?
-    return first_paragraph if first_paragraph.length <= TRUNCATION_THRESHOLD
+    return if raw_first_paragraph_text.nil?
 
-    truncated_paragraph = first_paragraph[0..TRUNCATION_THRESHOLD]
-    if (index_of_final_fullstop = truncated_paragraph.rindex ". ")
-      truncated_paragraph[0..index_of_final_fullstop]
+    text = raw_first_paragraph_text
+    return text if text.length <= TRUNCATION_THRESHOLD
+
+    truncated_text = text[0..TRUNCATION_THRESHOLD]
+    if (index_of_final_fullstop = text.rindex ". ")
+      truncated_text[0..index_of_final_fullstop]
     else
-      "%s..." % truncated_paragraph
+      "%s..." % truncated_text
     end
   end
 
@@ -57,7 +59,7 @@ class Lifer::Entry::Markdown < Lifer::Entry
   #
   # @return [String] The HTML for the body of the entry.
   def to_html
-    Kramdown::Document.new(body).to_html
+    @to_html ||= Kramdown::Document.new(body).to_html
   end
 
   private
@@ -75,25 +77,20 @@ class Lifer::Entry::Markdown < Lifer::Entry
     end.uniq
   end
 
-  # Using Kramdown we can detect the first paragraph of the entry.
+  # Detects the raw paragraph text from the entry.
   #
+  # @fixme It would be easier and less error prone to do this with Nokogiri. But
+  #   we currently don't need the dependency for any other reason, so let's
+  #   defer adding it until then.
   # @private
-  def first_paragraph
-    @first_paragraph ||=
-      kramdown_paragraph_text(
-        Kramdown::Document.new(body).root
-          .children
-          .detect { |child| child.type == :p }
-      )
-  end
+  def raw_first_paragraph_text
+    paragraphs = to_html.match %r{<p[^>]*>(.*?)</p>}im
+    paragraph = paragraphs ? paragraphs[1].strip : nil
 
-  # @private
-  def kramdown_paragraph_text(kramdown_element)
-    return if kramdown_element.nil?
+    return unless paragraph
 
-    kramdown_element.children
-      .flat_map { |child| child.value || kramdown_paragraph_text(child) }
-      .join
-      .gsub(/\n/, " ")
+    paragraph = paragraph.gsub /<\/?[^>]*>/, ""
+    paragraph = CGI.unescapeHTML paragraph
+    paragraph.gsub(/[\s\n\t]+/, " ").strip
   end
 end

data/lib/lifer/entry.rb

@@ -39,10 +39,6 @@ module Lifer
     #
     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
-
     # If tags are represented in YAML frontmatter as a string, they're split on
     # commas and/or spaces.
     #
@@ -147,7 +143,7 @@ module Lifer
     def body
       return full_text.strip unless frontmatter?
 
-      full_text.gsub(FRONTMATTER_REGEX, "").strip
+      full_text.gsub(Lifer::FRONTMATTER_REGEX, "").strip
     end
 
     def feedable?
@@ -168,7 +164,8 @@ module Lifer
       return {} unless frontmatter?
 
       Lifer::Utilities.symbolize_keys(
-        YAML.load(full_text[FRONTMATTER_REGEX, 1], permitted_classes: [Time])
+        YAML.load full_text[Lifer::FRONTMATTER_REGEX, 1],
+          permitted_classes: [Time]
       )
     end
 
@@ -326,6 +323,6 @@ module Lifer
       File.basename(file).match(FILENAME_DATE_FORMAT)[1]
     end
 
-    def frontmatter? = (full_text && full_text.match?(FRONTMATTER_REGEX))
+    def frontmatter? = (full_text && full_text.match?(Lifer::FRONTMATTER_REGEX))
   end
 end

data/lib/lifer/version.rb

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

data/lib/lifer.rb

@@ -24,6 +24,10 @@ module Lifer
     "(\\/\\.)+"   # Contains a dot directory.
   ] | IGNORE_DIRECTORIES.map { |d| "^(#{d})" }
 
+  # We expect frontmatter in any file to be provided in the following format.
+  #
+  FRONTMATTER_REGEX = /^---\n(.*)---\n/m
+
   class << self
     # 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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lifer
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.1
 platform: ruby
 authors:
 - benjamin wil
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-30 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
@@ -159,6 +159,7 @@ files:
 - lib/lifer/brain.rb
 - lib/lifer/builder.rb
 - lib/lifer/builder/html.rb
+- lib/lifer/builder/html/from_any.rb
 - lib/lifer/builder/html/from_erb.rb
 - lib/lifer/builder/html/from_liquid.rb
 - lib/lifer/builder/html/from_liquid/drops.rb
@@ -170,7 +171,6 @@ files:
 - 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
 - lib/lifer/builder/rss.rb
 - lib/lifer/builder/txt.rb
@@ -210,8 +210,8 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  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
+  homepage_uri: https://github.com/benjaminwil/lifer/blob/v0.10.1/README.md
+  source_code_uri: https://github.com/benjaminwil/lifer/tree/v0.10.1
   changelog_uri: https://github.com/benjaminwil/lifer/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []

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

@@ -1,66 +0,0 @@
-class Lifer::Builder::HTML::FromLiquid
-  # Note that if you want to learn more about the shape of this class, check out
-  # `Liquid::Block` in the `liquid` gem.
-  #
-  # The layout tag is a bit magic. The idea here is to emulate how Jekyll
-  # handles `layout:` YAML frontmatter within entries to change the normal
-  # parent layout to an override parent layout--but without the need for
-  # frontmatter.
-  #
-  # The reason we took this strategy was to avoid pre-processing every entry for
-  # 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.
-  #     {% layout "path/to/my_liquid_layout_template" %}
-  #
-  # (The required `endlayout` tag will be appended to the end of the file
-  # on render if you do not insert it yourself.
-  #
-  class LayoutTag < Liquid::Block
-    # The name of the tag in Liquid templates, `layout`.
-    #
-    NAME = :layout
-
-    # The end name of the tag in Liquid templates, `endlayout`.
-    #
-    ENDNAME = ("end%s" % NAME).to_sym
-
-    def initialize(layout, path, options)
-      @path = path.delete("\"").strip
-      super
-    end
-
-    # A layout tag wraps an entire document and outputs it inside of whatever
-    # the `@layout` is. This lets a child document specify a parernt layout!
-    # Very confusing stuff.
-    #
-    # @param context [Liquid::Context] All of the context of the Liquid
-    #   document that would be rendered.
-    # @return [String] A rendered document.
-    def render(context)
-      document_context = context.environments.first
-      parse_options = document_context["parse_options"]
-      liquid_file_system = parse_options[:environment].file_system
-      render_options = document_context["render_options"]
-
-      current_layout_file = File
-        .read(document_context["entry"]["collection"]["layout_file"])
-        .gsub(/\{%\s*#{tag_name}.+%\}/, "")
-
-      content_with_layout = Liquid::Template
-        .parse(current_layout_file, **parse_options)
-        .render(document_context, **render_options)
-
-      Liquid::Template
-        .parse(
-          liquid_file_system.read_template_file(@path),
-          **parse_options
-        )
-        .render(
-          document_context.merge({"content" => content_with_layout}),
-          **render_options
-        )
-    end
-  end
-end