distorted-jekyll 0.5.6 → 0.5.7

data/lib/distorted-jekyll/injection_of_love.rb

@@ -0,0 +1,305 @@
+require 'kramdown'
+
+# Replace standard Markdown image syntax with instances of DistorteD
+# via its Liquid tag.
+#
+#
+### SYNTAX
+#
+# I'm calling individual media elements "images" here because I'm overloading
+# the Markdown image syntax to express them. There is no dedicated
+# syntax for other media types in any flavor of Markdown as of 2019,
+# so that seemed like the cleanest and sanest way to deal
+# with non-images in DistorteD.
+#
+# DistorteD::Invoker will do the media type inspection and handling
+# once we get into Liquid Land. This is the approach suggested by
+# CommonMark: https://talk.commonmark.org/t/embedded-audio-and-video/441/15
+#
+# Media elements will display as a visibly related group when
+# two or more Markdown image tags exist in consecutive Markdown
+# unordered (e.g. *-+) list item or ordered (e.g. 1.) list item lines.
+# Their captions should be hidden until opened in a lightbox or as a tooltip
+# on desktop browsers via ::hover state.
+#
+# The inspiration for this display can be seen in the handling
+# of two, three, or four images in any single post on Tw*tter.
+# DistorteD expands on the concept by supporting things such as groups
+# of more than four media elements and elements of heterogeneous media types.
+#
+# Standalone image elements (not contained in list item) should be displayed
+# as single solo elements spanning the entire usable width of the
+# container element, whatever that happens to be at the point where
+# our regex excised a block of Markdown for us to work with.
+#
+#
+### TECHNICAL CONSIDERATIONS
+#
+# Jekyll processes Liquid templates before processing page/post Markdown,
+# so we can't rely on customizing the Markdown renderer's `:img` element
+# output as a means to invoke DistorteD.
+# https://jekyllrb.com/tutorials/orderofinterpretation/
+#
+# Prefer the POSIX-style bracket expressions (e.g. [[:digit:]]) over
+# basic character classes (e.g. \d) in regex because they match Unicode
+# instead of just ASCII.
+# https://ruby-doc.org/core/Regexp.html#class-Regexp-label-Character+Classes
+#
+#
+### INLINE ATTRIBUTE LISTS
+#
+# Support additional arguments passed to DistorteD via Kramdown-style
+# inline attribute lists.
+# https://kramdown.gettalong.org/syntax.html#images
+# https://kramdown.gettalong.org/syntax.html#inline-attribute-lists
+#
+# IALs can be on the same line or on a line before or after their
+# associated flow element.
+# In ambiguous situations (flow elements both before and after an IAL),
+# the IAL applies to the flow element before it.
+# All associated elements and IALs must be on contiguous lines.
+#
+# This page provides a regex for parsing IALs, Section 5.3:
+# https://golem.ph.utexas.edu/~distler/maruku/proposal.html
+#
+#
+### SOLUTION
+#
+# A `pre_render` hook uses this regex to process Markdown source files
+# and replace instances of the Markdown image syntax with instances of
+# DistorteD's Liquid tags.
+# Single images will be replaced with {% distorted %}.
+# Multiple list-item images will be replaced with a {% distort %} block.
+#
+# By doing with with a regex (sorry!!) I hope to avoid a hard dependency on
+# any one particular Markdown engine. Though I only support Kramdown for now,
+# any engine that supports IALs should be fine.
+#
+# High-level explanation of what we intend to match:
+#
+# {:optional_ial => line_before_image}  # Iff preceded by a blank line!
+# (optional_list_item)? ![alt](image){:optional_ial => same_line}
+# {:optional_ial => next_consecutive_line}
+# Repeat both preceding matches (together) any number of times to parse
+# a {% distort %} block.
+# See inline comments below for more detail.
+MD_IMAGE_REGEX = %r&
+  # Matching group of a single image tag.
+  (
+    # Optional preceding-line attribute list.
+    (
+      # One blank line, because:
+      # "If a block IAL is directly after and before a block-level element,
+      #  it is applied to preceding element."  —Kramdown BAL docs
+      #
+      # /\R/ - A linebreak: \n, \v, \f, \r \u0085 (NEXT LINE),
+      #   \u2028 (LINE SEPARATOR), \u2029 (PARAGRAPH SEPARATOR) or \r\n.
+      ^$\R
+      # Any amount of blank space on the line before block IAL
+      ^[[:blank:]]*
+      # IAL regex from Section 5.3:
+      # https://golem.ph.utexas.edu/~distler/maruku/proposal.html
+      (?<block_ial_before>\{:(\\\}|[^\}])*\})
+      # Any amount of trailing whitespace followed by a newline.
+      [[:blank:]]*$\R
+    )?  # Match all of that, or nothing.
+    # Begin matching the line that contains an image.
+    ^
+    # Match anything that might be between that start-of-line
+    # and the first character (!) of an image.
+    (
+      # From Gruber's original Markdown page:
+      # "List markers typically start at the left margin, but may be indented
+      # by up to three spaces."
+      # Include both unordered (-+*) and ordered (\d\. like `1.`) lists.
+      (?<li>[ ]{0,3}[-\*\+|\d\.]
+      # Support an optional IAL for the list element as shown in Kramdown docs:
+      # https://kramdown.gettalong.org/syntax.html#lists
+      # Ctrl+F "{:.cls}"
+      (?<li_ial>\{:(\\\}|[^\}])*\})?
+      # "List markers must be followed by one or more spaces or a tab."
+      # https://daringfireball.net/projects/markdown/syntax#list
+      ([ ]+|\t))
+    )?  # Although any preceding elements are optional!
+    # Match Markdown image syntax:
+    #   ![alt text](/some/path/to/image.png 'title text'){:other="options"}
+    #   beginning with the alt tag:
+    !\[(?<alt>(\\[[:print:]]|[^\]])*)\]
+    # Continuing with img src as anything after the '(' and before ')' or
+    # before anything that could be a title.
+    # Assume titles will be quoted.
+    \((?<src>(\\[[:print:]]|[^'")]+))
+    # Title is optional.
+    # Ignore double-quotes in single-quoted titles and single-quotes
+    # in double-quoted titles otherwise we can't use contractions.
+    # Don't include the title's opening or closing quotes in the capture.
+    ('(?<title>(\\[[:print:]]|[^']*))'|"(?<title>(\\[[:print:]]|[^"]*))")?
+    # The closing ')' will always be present, title or no.
+    \)
+    # Optional IAL on the same line as the :img element **with no space between them**:
+    # "A span IAL (or two or more span IALs) has to be put directly after
+    #  the span-level element to which it should be applied, no additional
+    #  character is allowed between, otherwise it is ignored and only
+    #  removed from the output."  —Kramdown IAL docs
+    (?<span_ial>\{:(\\\}|[^\}])*\})*[[:print:]]*$\R
+    # Also support optional BALs on the lines following the image.
+    (^[[:blank:]]*(?<block_ial_after>\{:(\\\}|[^\}])*\})+$\R)*
+  )+  # Capture multiple images together for block display.
+&x
+
+
+def md_injection
+  Proc.new { |document, payload|
+    # Compare any given document's file extension to the list of enabled
+    # Markdown file extensions in Jekyll's config.
+    if payload['site']['markdown_ext'].include? document.extname.downcase[1..-1]
+      # Convert Markdown images to {% distorted %} tags.
+      #
+      # Use the same Markdown parser as Jekyll to avoid parsing inconsistencies
+      # between this pre_render hook and the main Markdown render step.
+      # This is still effectively a Markdown-parsing regex (and still
+      # effectively a bad idea lol) but it's the cleanest way I can come up
+      # with right now for separating DistorteD-destined Markdown from
+      # the rest of any given page.
+      # NOTE: Attribute List Definitions elsewhere in a Markdown document
+      # will be lost when converting this way. I might end up just parsing
+      # the entire document once with my own `to_liquid` converter, but I've been
+      # avoiding that as it seems wasteful because Jekyll then renders the entire
+      # Markdown document a second time immediately after our Liquid tag.
+      # It's fast enough that I should stop trying to prematurely optimize this :)
+      # TODO: Implement MD → DD love using only the #{CONFIGURED_MARKDOWN_ENGINE},
+      # searching for :img elements inside :li elements to build BLOCKS.
+      document.content = document.content.gsub(MD_IMAGE_REGEX) { |match| 
+        Kramdown::Document.new(match).to_liquid
+      }
+    end
+  }
+end
+
+
+# Kramdown implementation of Markdown AST -> Liquid converter.
+# Renders Markdown element attributes as key=value, also under the assumption
+# of using gem 'liquid-tag-parser': https://github.com/dmalan/liquid-tag-parser
+module Kramdown
+  module Converter
+    class Liquid < Base
+
+      # The incoming parsed Markdown tree will include many spurious elements,
+      # like container paragraph elements and the list item elements when
+      # parsing DD Grid style Markdown. Use this function to map a tree of
+      # arbitrary elements to a flat list of elements of a single type.
+      def children(el, type)
+        matched = []
+
+        if el.is_a? Enumerable
+        # We might want to run this against an Array output from an
+        # earlier invokation of this method.
+          el.each {
+            |item| matched.push(*children(item, type))
+          }
+        elsif el.type.equal? type
+          # If we find the type we're looking for, stop and return it.
+          # Let it bring its children along with it instead of recursing
+          # into them. This will let us match container-only elements
+          # such as <li> by type without considering the type of its children,
+          # for situation where its children are really what we want.
+          matched.push(el)
+        else
+          # Otherwise keep looking down the tree.
+          unless el.children.empty?
+            el.children.each {
+              |child| matched.push(*children(child, type))
+            }
+          end
+        end
+        matched
+      end
+
+      def attrs(el, type = :img)
+        matched = []
+
+        if el.is_a? Enumerable
+          # Support an Array of elements...
+          el.each {
+            |child| matched.push(*attrs(child, type))
+          }
+        else
+          # ...or a tree of elements.
+          if el.type.equal? type
+            # Images won't have a `:value` — only `:attr`s — and the only
+            # important things in their `:options` (e.g. IAL contents)
+            # will be duplicated in `class` or some other `:attr` anyway.
+            # Those things should be added here if this is ever used in a
+            # more generic context than just parsing the image tags.
+            matched << el.attr unless el.attr.empty?
+          end
+          unless el.children.empty?
+            # Keep looking even if this element was one we are looking for.
+            el.children.each {
+              |child| matched.push(*attrs(child, type))
+            }
+          end
+        end
+        matched
+      end
+
+      # Convert Markdown element attributes to a string key=value,
+      # except for `src` (DD-specific)
+      def to_attrs(k, v)
+        # DistorteD prefers the media filename as a positional argument,
+        # not a named kwarg.
+        if k == 'src'
+          v.to_s
+        else
+          k.to_s + '="' + v.to_s + '"'
+        end
+      end
+
+      def distorted(attrs)
+        "{% distorted #{attrs.map{|k,v| to_attrs(k, v)}.join(' ')} %}"
+      end
+
+      # Kramdown entry point
+      def convert(el)
+        # The parsed "images" may also be audio, video, or some other
+        # media type. There is only one Markdown image tag, however.
+        imgs = children(el, :img)
+
+        # Enable conceptual-grouping (BLOCKS) mode if the count of list item
+        # elements matches the count of image elements in our
+        # chunk of Markdown. Technically I should check to make sure each
+        # image is the child of one of those list items,
+        # but this is way easier until I (hopefully never) find a parsing
+        # corner-case where this doesn't hold up.
+        lists = children(el, :li)
+        list_imgs = lists.map{|li| children(li, :img)}.flatten
+
+        case lists.count
+        when 0..1
+          # Render one (1) image/video/whatever. This behavior is the same
+          # regardless if the image is in a single-item list or just by itself.
+          distorted(attrs(imgs.first)&.first&.merge({
+            # Images default to `attention` cropping for desktop/mobile versatility.
+            # Override this for single images unless a cropping value was already set.
+            'crop'.freeze => attrs(imgs.first)&.first&.dig('crop'.freeze) || 'none'.freeze,
+          }))
+        else
+          # Render a conceptual group (DD::BLOCKS)
+
+          if imgs.count != list_imgs.count
+            # Sanity check :img count vs :img-in-:li count.
+            # We should support the corner case where the regex matches
+            # multiple consecutive lines, but with mixed list item status,
+            # e.g. a solo image abuts a conceptual group and gets globbed
+            # into a single match.
+            # For now, however:
+            raise "MD->img regex returned an unequal number of listed and unlisted tags."
+          end
+
+          "{% distort -%}\n#{list_imgs.map{|img| distorted(*attrs(img))}.join("\n")}\n{% enddistort %}"
+        end
+      end
+
+    end
+  end
+end

data/lib/distorted-jekyll/invoker.rb

@@ -0,0 +1,400 @@
+# Our custom Exceptions
+require 'distorted-jekyll/error_code'
+
+# Configuration-loading code
+require 'distorted-jekyll/floor'
+
+# Configuration data manipulations
+require 'distorted-jekyll/molecule/abstract'
+
+# Media-type drivers
+require 'distorted-jekyll/molecule/font'
+require 'distorted-jekyll/molecule/image'
+require 'distorted-jekyll/molecule/text'
+require 'distorted-jekyll/molecule/pdf'
+require 'distorted-jekyll/molecule/svg'
+require 'distorted-jekyll/molecule/video'
+require 'distorted-jekyll/molecule/last-resort'
+
+# Set.to_hash
+require 'distorted/monkey_business/set'
+
+# Slip in and out of phenomenon
+require 'liquid/tag'
+require 'liquid/tag/parser'
+
+# Explicitly required for l/t/parser since a1cfa27c27cf4d4c308da2f75fbae88e9d5ae893
+require 'shellwords'
+
+# Set is in stdlib but is not in core.
+require 'set'
+
+# MIME Magic 🧙‍♀️
+require 'mime/types'
+require 'ruby-filemagic'
+
+# I mean, this is why we're here, right?
+require 'jekyll'
+
+
+module Jekyll
+  module DistorteD
+    class Invoker < Liquid::Tag
+
+      GEM_ROOT = File.dirname(__FILE__).freeze
+
+      # Mix in config-loading methods.
+      include Jekyll::DistorteD::Molecule::Abstract
+
+      # Enabled media_type drivers. These will be attempted back to front.
+      # TODO: Make this configurable.
+      MEDIA_MOLECULES = [
+        Jekyll::DistorteD::Molecule::LastResort,
+        Jekyll::DistorteD::Molecule::Font,
+        Jekyll::DistorteD::Molecule::Text,
+        Jekyll::DistorteD::Molecule::PDF,
+        Jekyll::DistorteD::Molecule::SVG,
+        Jekyll::DistorteD::Molecule::Video,
+        Jekyll::DistorteD::Molecule::Image,
+      ]
+
+      # Any any attr value will get a to_sym if shorter than this
+      # totally arbitrary length, or if the attr key is in the plugged
+      # Molecule's set of attrs that take only a defined set of values.
+      # My chosen boundary length fits all of the outer-limit tag names I use,
+      # like 'medium'. It fits the longest value of Vips::Interesting too,
+      # though `crop` will be symbolized based on the other condition.
+      ARBITRARY_ATTR_SYMBOL_STRING_LENGTH_BOUNDARY = 13
+
+
+      # 𝘏𝘖𝘞 𝘈𝘙𝘌 𝘠𝘖𝘜 𝘎𝘌𝘕𝘛𝘓𝘌𝘔𝘌𝘕 ！！
+      def initialize(tag_name, arguments, liquid_options)
+        super
+        # Tag name as given to Liquid::Template.register_tag().
+        @tag_name = tag_name.to_sym
+
+        # Liquid leaves argument parsing totally up to us.
+        # Use the envygeeks/liquid-tag-parser library to wrangle them.
+        parsed_arguments = Liquid::Tag::Parser.new(arguments)
+
+        # Filename is the only non-keyword argument our tag should ever get.
+        # It's spe-shul and gets its own definition outside the attr loop.
+        if parsed_arguments.key?(:src)
+          @name = parsed_arguments[:src]
+        else
+          @name = parsed_arguments[:argv1]
+        end
+
+        # If we didn't get one of the two above options there is nothing we
+        # can do but bail.
+        unless @name
+          raise "Failed to get a usable filename from #{arguments}"
+        end
+
+        # Guess MIME Magic from the filename. For example:
+        # `distorted IIDX-Readers-Unboxing.jpg: [#<MIME::Type: image/jpeg>]`
+        #
+        # Types#type_for can return multiple possibilities for a filename.
+        # For example, an XML file: [application/xml, text/xml].
+        mime = MIME::Types.type_for(@name).to_set
+
+        # We can't proceed without a usable media type.
+        # Look at the actual file iff the filename wasn't enough to guess.
+        unless mime.empty?
+          Jekyll.logger.debug(@tag_name, "Detected #{@name} media types: #{mime}")
+        else
+          # Did we fail to guess any MIME::Types from the given filename?
+          # We're going to have to look at the actual file
+          # (or at least its first four bytes).
+          # `@mime` will be readable/writable in the FileMagic.open block context
+          # since it was already defined in the outer scope.
+          FileMagic.open(:mime) do |fm|
+            # TODO: Support finding files in paths deeper than the Site source.
+            # There's no good way to get the path here of the Markdown file
+            # that included our Tag, so relative paths won't work if given
+            # as just a filename. It should work if supplied like:
+            #   ![The coolest image ever](/2020/04/20/some-post/hahanofileextension)
+            # This limitation is normally not a problem since we can guess
+            # the MIME::Types just based on the filename.
+            # It would be possible to supply the Markdown document's path
+            # as an additional argument to {% distorted %} when converting
+            # Markdown in `injection_of_love`, but I am resisting that
+            # approach because it would make DD's Liquid and Markdown entrypoints
+            # no longer exactly equivalent, and that's not okay with me.
+            test_path = File.join(
+              Jekyll::DistorteD::Floor::config(:source),
+              Jekyll::DistorteD::Floor::config(:collections_dir),
+              @name,
+            )
+            # The second argument makes fm.file return just the simple
+            # MIME::Type String, e.g.:
+            #
+            # irb(main):006:1*   fm.file('/home/okeeblow/IIDX-turntable.svg')
+            # => "image/svg+xml; charset=us-ascii"
+            # irb(main):009:1*   fm.file('/home/okeeblow/IIDX-turntable.svg', true)
+            # => "image/svg"
+            #
+            # However MIME::Types won't take short variants like 'image/svg',
+            # so explicitly have FM return long types and split it ourself
+            # on the semicolon:
+            #
+            # irb(main):038:0> "image/svg+xml; charset=us-ascii".split(';').first
+            # => "image/svg+xml"
+            mime = Set[MIME::Types[fm.file(@name, false).split(';'.freeze).first]]
+          end
+
+          # Did we still not get a type from FileMagic?
+          unless mime
+            if Jekyll::DistorteD::Floor::config(self.class.const_get(:CONFIG_ROOT), :last_resort)
+              Jekyll.logger.debug(@tag_name, "Falling back to bare <img> for #{@name}")
+              mime = Jekyll::DistorteD::Molecule::LastResort::MIME_TYPES
+            else
+              raise MediaTypeNotFoundError.new(@name)
+            end
+          end
+        end
+
+        # Array of drivers to try auto-plugging. Take a shallow copy first because
+        # these will get popped off the end for plug attempts.
+        media_molecules = MEDIA_MOLECULES.dup
+
+        ## Media Driver Autoplugging
+        #
+        # Take the union of this file's detected MIME::Types and
+        # the supported MEDIA_TYPES declared in each molecule.
+        # Molecules will likely declare their Types with a regex:
+        # https://rdoc.info/gems/mime-types/MIME%2FTypes:[]
+        #
+        #
+        # Still-Image Mime::Types Example:
+        # MIME::Types.type_for('IIDX-Readers-Unboxing.jpg')
+        # => [#<MIME::Type: image/jpeg>]
+        #
+        # Video MIME::Types Example:
+        # MIME::Types.type_for('play.mp4') => [
+        #   #<MIME::Type: application/mp4>,
+        #   #<MIME::Type: audio/mp4>,
+        #   #<MIME::Type: video/mp4>,
+        #   #<MIME::Type: video/vnd.objectvideo>
+        # ]
+        #
+        #
+        # Molecule declared-supported MIME::Types Example:
+        # (huge list)
+        #   MIME_TYPES = MIME::Types[/^#{MEDIA_TYPE}/, :complete => true]
+        #
+        #
+        # Detected & Declared MIME::Types Union Example:
+        # MIME::Types.type_for('play.mp4') & MIME::Types[/^video/, :complete => true]
+        # => [#<MIME::Type: video/mp4>, #<MIME::Type: video/vnd.objectvideo>]
+        #
+        # ^ This non-empty example union means we sould try this driver for this file.
+        #
+        #
+        # Loop until we've found a match or tried all available drivers.
+        loop do
+          # Attempt to plug the last driver in the array of enabled drivers.
+          molecule = media_molecules.pop
+
+          # This will be nil once we've tried them all and run out and are on the last loop.
+          if molecule == nil
+            if Jekyll::DistorteD::Floor::config(self.class.const_get(:CONFIG_ROOT), :last_resort)
+              Jekyll.logger.debug(@tag_name, "Falling back to a bare <img> for #{name}")
+              @mime = Jekyll::DistorteD::Molecule::LastResort::MIME_TYPES
+              molecule = Jekyll::DistorteD::Molecule::LastResort
+            else
+              raise MediaTypeNotImplementedError.new(@name)
+            end
+          end
+
+          Jekyll.logger.debug(@tag_name, "Trying to plug #{@name} into #{molecule}")
+
+          # We found a potentially-compatible driver iff the union set is non-empty.
+          if not (mime & molecule.const_get(:MIME_TYPES)).empty?
+            @mime = mime & molecule.const_get(:MIME_TYPES)
+            Jekyll.logger.debug(@tag_name, "Enabling #{molecule} for #{@name}: #{mime}")
+
+            # Override Invoker's stubs by prepending the driver's methods to our DD instance's singleton class.
+            # https://devalot.com/articles/2008/09/ruby-singleton
+            # `self.singleton_class.extend(molecule)` doesn't work in this context.
+            self.singleton_class.instance_variable_set(:@media_molecule, molecule)
+
+            # Set instance variables for the combined set of HTML element
+            # attributes used for this media_type. The global set is defined in this file
+            # (Invoker), and the media_type-specific set is appended to that during auto-plug.
+            attrs = (self.singleton_class.const_get(:GLOBAL_ATTRS) + molecule.const_get(:ATTRS)).to_hash
+            attrs.each_pair do |attr, val|
+              # An attr supplied to the Liquid tag should override any from the config
+              liquid_val = parsed_arguments&.dig(attr)
+              # nil.to_s is '', so print 'nil' for readability.
+              Jekyll.logger.debug("Liquid #{attr}", liquid_val || 'nil')
+
+              if liquid_val.is_a?(String)
+                # Symbolize String values of any attr that has a Molecule-defined list
+                # of acceptable values, or — completely arbitrarily — any String value
+                # shorter than an arbitrarily-chosen constant.
+                # Otherwise freeze them.
+                if (liquid_val.length <= ARBITRARY_ATTR_SYMBOL_STRING_LENGTH_BOUNDARY) or
+                    molecule.const_get(:ATTRS_VALUES).key?(attr)
+                  liquid_val = liquid_val&.to_sym
+                elsif liquid_val.length > ARBITRARY_ATTR_SYMBOL_STRING_LENGTH_BOUNDARY
+                  # Will be default in Ruby 3.
+                  liquid_val = liquid_val&.freeze
+                end
+              end
+
+              attrs[attr] = liquid_val
+            end
+
+            # Save attrs to our instance as the data source for Molecule::Abstract.attrs.
+            @attrs = attrs
+
+            # Plug the chosen Media Molecule!
+            # Using Module#prepend puts the Molecule's ahead in the ancestor chain
+            # of any defined here, or any defined in an `include`d module.
+            (class <<self; prepend @media_molecule; end)
+
+            # Break out of the `loop`, a.k.a. stop auto-plugging!
+            break
+          end
+
+        end
+      end
+
+      # Called by Jekyll::Renderer
+      # https://github.com/jekyll/jekyll/blob/HEAD/lib/jekyll/renderer.rb
+      # https://jekyllrb.com/tutorials/orderofinterpretation/
+      def render(context)
+        render_to_output_buffer(context, '')
+      end
+
+      # A future Liquid version (5.0?) will call this function directly
+      # instead of calling render()
+      def render_to_output_buffer(context, output)
+        # Get Jekyll Site object back from tag rendering context registers so we
+        # can get configuration data and path information from it and
+        # then pass it along to our StaticFile subclass.
+        site = context.registers[:site]
+
+        # The rendering context's `first` page will be the one that invoked us.
+        page_data = context.environments.first['page'.freeze]
+
+        #
+        # Our subclass' additional args:
+        # dest - The String path to the generated `url` folder of the page HTML output
+        base = site.source
+
+        # `relative_path` doesn't seem to always exist, but `path` does? idk.
+        # I was testing with `relative_path` only with `_posts`, but it broke
+        # when I invoked DD on a _page. Both have `path`.
+        dir = File.dirname(page_data['path'.freeze])
+
+        # Every one of Ruby's `File.directory?` / `Pathname.directory?` /
+        # `FileTest.directory?` methods actually tests that path on the
+        # real filesystem, but we shouldn't look at the FS here because
+        # this function gets called when the Site.dest directory does
+        # not exist yet!
+        # Hackily look at the last character to see if the URL is a
+        # directory (like configured on cooltrainer) or a `.html`
+        # (or other extension) like the default Jekyll config.
+        # Get the dirname if the url is not a dir itself.
+        @dd_dest = @url = page_data['url'.freeze]
+        unless @dd_dest[-1] == Jekyll::DistorteD::Floor::PATH_SEPARATOR
+          @dd_dest = File.dirname(@dd_dest)
+          # Append the trailing slash so we don't have to do it
+          # in the Liquid templates.
+          @dd_dest << Jekyll::DistorteD::Floor::PATH_SEPARATOR
+        end
+
+        # Create an instance of the media-appropriate Jekyll::StaticFile subclass.
+        #
+        # StaticFile args:
+        # site        - The Jekyll Site object.
+        # base        - The String path to the Jekyll::Site.source, e.g. /home/okeeblow/Works/cooltrainer
+        # dir         - The String path between <base> and the source file, e.g. _posts/2018-10-15-super-cool-post
+        # name        - The String filename of the original media, e.g. cool.jpg
+        # mime        - The Set of MIME::Types of the original media.
+        # attrs       - The Set of attributes given to our Liquid tag, if any.
+        # dd_dest     - The String path under Site.dest to DD's top-level media output directory.
+        # url         - The URL of the page this tag is on.
+        static_file = self.static_file(
+          site,
+          base,
+          dir,
+          @name,
+          @mime,
+          @attrs,
+          @dd_dest,
+          @url,
+        )
+
+        # Add our new file to the list that will be handled
+        # by Jekyll's built-in StaticFile generator.
+        # Our StaticFile children implement a write() that invokes DistorteD,
+        # but this lets us avoid writing our own Generator.
+        site.static_files << static_file
+      end
+
+      # Called by a Molecule-specific render() method since they will
+      # all load their Liquid template files in the same way.
+      # Bail out if this is not handled by the module we just mixed in.
+      # Any media Molecule must override this to return an instance of
+      # their media-type-appropriate StaticFile subclass.
+      def static_file(site, base, dir, name, mime, attrs, dd_dest, url)
+        raise MediaTypeNotImplementedError.new(name)
+      end
+
+      # Generic Liquid template loader that will be used in every MediaMolecule.
+      # Callers will call `render(**{:template => vars})` on the Object returned
+      # by this method.
+      def parse_template(site: nil, name: nil)
+        site = site || Jekyll.sites.first
+        begin
+          # Use a given filename, or detect one based on media-type.
+          if name.nil?
+            # Template filename is based on the MEDIA_TYPE and/or SUB_TYPE declared
+            # in the plugged MediaMolecule for the given input file.
+            if self.singleton_class.const_defined?(:SUB_TYPE)
+              name = "#{self.singleton_class.const_get(:SUB_TYPE)}.liquid".freeze
+            else
+              name = "#{self.singleton_class.const_get(:MEDIA_TYPE)}.liquid".freeze
+            end
+          elsif not name.include?('.liquid'.freeze)
+            # Support filename arguments with and without file extension.
+            # The given String might already be frozen, so concatenating
+            # the extension might fail. Just set a new version.
+            name = "#{name}.liquid"
+          end
+          template = File.join(
+            self.singleton_class.const_get(:GEM_ROOT),
+            'template'.freeze,
+            name,
+          )
+
+          # Jekyll's Liquid renderer caches in 4.0+.
+          if Jekyll::DistorteD::Floor::config(
+              Jekyll::DistorteD::Floor::CONFIG_ROOT,
+              :cache_templates,
+          )
+            # file(path) is the caching function, with path as the cache key.
+            # The `template` here will be the full path, so no versions of this
+            # gem should ever conflict. For example, right now during dev it's:
+            # `/home/okeeblow/Works/DistorteD/lib/image.liquid`
+            Jekyll.logger.debug('DistorteD', "Parsing #{template} with caching renderer.")
+            site.liquid_renderer.file(template).parse(File.read(template))
+          else
+            # Re-read the template just for this piece of media.
+            Jekyll.logger.debug('DistorteD', "Parsing #{template} with fresh (uncached) renderer.")
+            Liquid::Template.parse(File.read(template))
+          end
+
+        rescue Liquid::SyntaxError => l
+          # This shouldn't ever happen unless a new version of Liquid
+          # breaks syntax compatibility with our templates somehow.
+          l.message
+        end
+      end  # parse_template
+
+    end
+  end
+end