distorted-jekyll 0.5.4 → 0.7.0

data/lib/distorted-jekyll/liquid_liquid.rb

@@ -0,0 +1,255 @@
+require 'liquid/drop'
+require 'liquid/template'
+
+
+module Cooltrainer
+
+  # DistorteD Liquid::Template-caching Hash.
+  # Jekyll has its own Liquid cache enabled by default as of 4.0,
+  # but the Jekyll::LiquidRenderer::File has a different interface
+  # than Liquid::Template (e.g. no :assigns accessor).
+  @@watering rescue begin
+    @@watering = Hash[]
+  end
+
+
+  # Entry-point for MediaMolecules to render HTML (and maybe eventually other formats!).
+  #
+  # Liquid is arguably a poor choice for this use case since it is designed
+  # to handle arbitrary user-supplied templates in a safe way,
+  # versus e.g. ERB which allows in-template execution of arbitrary Ruby code,
+  # but our templates are bundled here in the Gem (ostensibly) should be trustworthy.
+  #
+  # I considered using Nokogiri's DocumentFragment Builder instead:
+  # fragment = Nokogiri::HTML::DocumentFragment.parse(''.freeze)
+  # Nokogiri::HTML::Builder.with(fragment) do |doc|
+  #   doc.picture {
+  #     changes.each { |change| doc.source(:srcset=change.name) }
+  #   }
+  # end
+  # fragment.to_html
+  #
+  # But the way DistorteD works (with MIME::Type#distorted_template_method)
+  # means we would need a way to collate child elements anyway, since each call
+  # to a :distorted_template_method should generate only one variation,
+  # meaning we'd end up with a bunch of <source> tag Strings but would
+  # still need to collect them under a parent <picture> with a sibling <img>.
+  #
+  # Liquid is already heavily used by Jekyll, and of course DistorteD-Jekyll
+  # itself is a Liquid::Tag, so we may as well use it.
+  # Nokogiri, on the other hand, is not an explicit dependency of Jekyll.
+  # It will most likely be available, and DD itself pulls it in via SVGO
+  # and others, but Liquid will also allow us the flexibility to render
+  # formats other than just HTML/XML, e.g. BBCode or even Markdown.
+  #
+  # I might revisit this design decision once I experience working with more
+  # media formats and in more page contexts :)
+  ElementalCreation = Struct.new(:element, :name, :parents, :children, :template, :assigns, :change, keyword_init: true) do
+
+    def initialize(element, change = nil, parents: nil, children: nil, template: nil, assigns: Hash[])
+      super(
+        # Symbol Template name, corresponding to a Liquid template file name,
+        # not necessarily corresponding to the exact name of the element we return.
+        element: element,
+        change: change,
+        name: change&.name || element,
+        # Symbol name or Enumerable[Symbol] names of parent Element(s) we should be under,
+        # in order from outermost to innermost nesting.
+        # This is used to collate Change templates under a required parent Element,
+        # e.g. <source> tags must be under a <picture> or a <video> tag.
+        parents: parents.nil? ? nil : (parents.is_a?(Enumerable) ? parents.to_a : Array[parents]),
+        # Set up a Hash to store any children of this element in an Array-like way
+        # using auto-incrementing Integer keys. Its `&default_proc` responds to Symbol Element names,
+        # uses :detect to search for and return the first instance of that Symbol iff one exists,
+        # and if not it instantiates an Element Struct for that symbol and stores it.
+        children: Hash.new { |children_hash, element| children_hash.values.detect(
+          # Enumerable#detect will call this `ifnone` Proc if :detect's block returns nil.
+          # This Proc will instantiate a new Element with a copy of our :change, then store and return it.
+          # Can remove the destructured empty Hash once Ruby 2.7 is gone.
+          ->{ children_hash.store(children_hash.length, self.class.new(element, change, **{}))}
+        ) { |child| child.element == element } if element.is_a?(Symbol) }.tap { |children_hash|
+          # Merge the children-given-to-initialize() into our Hash.
+          case children
+          when Array then children.map.with_index.with_object(children_hash) { |(v, i), h| h.store(i, v) }
+          when Hash then ch.merge(children)
+          end
+        },
+        # Our associated Liquid::Template, based on our element name.
+        template: template || self.WATERING(element),
+        # Container of variables we want to render in Liquid besides what's covered by the basics.
+        assigns: assigns,
+      )
+
+      # Go ahead and define accessors for any assigns we already know about.
+      # Others are supported via the :method_missing below.
+      assigns.each_key { |assign|
+        define_method(assign) do; self[:assigns].fetch(assign, nil); end
+        define_method("#{assign.to_s}=") do |value|; self[:assigns].store(assign, value); end
+      }
+    end
+
+    # Hash[String] => Integer containing weights for MIME::Type#sub_type sorting weights.
+    # Weights are assigned in auto-incrementing Array order and will be called from :<=>.
+    # Sub-types near the beginning will sort before sub-types near the bottom.
+    # This is important for things like <picture> tags where the first supported <source> child
+    # encountered is the one that will be used, so we want vector types (SVG) to come first,
+    # then modern annoying formats like AVIF/WebP, then old standby types like PNG.
+    # TODO: Sort things other than Images
+    SORT_WEIGHTS = [
+      'svg+xml'.freeze,
+      'avif'.freeze,
+      'webp'.freeze,
+      'png'.freeze,
+      'jpeg'.freeze,
+      'gif'.freeze,
+    ].map.with_index.to_h
+    # Return a static 0 weight for unknown sub_types.
+    SORT_WEIGHTS.default_proc = Proc.new { 0 }
+
+    # Elements should sort themselves under their parent when rendering.
+    # Use predefined weights, e.g.:
+    #   irb> SORT_WEIGHTS['avif']
+    #   => 1
+    #   irb> SORT_WEIGHTS['png']
+    #   => 3
+    #   irb> SORT_WEIGHTS['avif'] <=> SORT_WEIGHTS['png']
+    #   => -1
+    def <=>(otra)
+      SORT_WEIGHTS[self.change&.type&.sub_type] <=> SORT_WEIGHTS[otra&.change&.type&.sub_type]
+    end
+
+    # Take a child Element and store it.
+    # If it requests no parents, store it with us.
+    # If it requests a parent, forward it there to the same method.
+    def mad_child(moon_child)
+      parent = moon_child.parents&.shift
+      if parent.nil?  # When shifting/popping an empty :parents Array
+        # Store the child with an incrementing Integer key as if
+        # self[Lchildren] were an Array
+        self[:children].store(self[:children].length, moon_child)
+      else
+        # Forward the child to the next level of ElementalCreation.
+        # The Struct will be instantiated by the :children Hash's &default_proc
+        self[:children][parent].mad_child(moon_child)
+      end
+    end
+
+    # Generic Liquid template loader
+    # Jekyll's site-wide Liquid renderer caches in 4.0+ and is usable via
+    # `site.liquid_renderer.file(cache_key).parse(liquid_string)`,
+    # but the Jekyll::LiquidRenderer::File you get back doesn't let us
+    # play with the `assigns` directly, so I stopped using the site renderer
+    # in favor of our own cache.
+    def WATERING(template_filename)
+      begin
+        # Memoize parsed Templates to this Struct subclass.
+        @@watering[template_filename] ||= begin
+          template = File.join(__dir__, 'liquid_liquid'.freeze, "#{template_filename}.liquid".freeze)
+          Jekyll.logger.debug('DistorteD::WATERING', template)
+          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  #WATERING 
+
+    # Returns the rendered String contents of this and all child Elements.
+    def render
+      self[:template].render(
+        self[:assigns].merge(Hash[
+          # Most Elements will be associated with a Change Struct
+          # encapsulating a single wanted variation on the source file.
+          :change => self[:change].nil? ? nil : Cooltrainer::ChangeDrop.new(self[:change]),
+          # Create Elements for every wanted child if they were only given
+          # to us as Symbols, then render them all to Strings to include
+          # in our own output.
+          :children => self[:children]&.values.map { |child|
+            child.is_a?(Symbol) ? self.class.new(child, self[:change], parents: self[:name], assigns: self[:assigns]) : child
+          }.sort.map(&:render),  # :sort will use ElementalCreation's :<=> method.
+        ]).transform_keys(&:to_s).transform_values { |value|
+          # Liquid wants String keys and values, not Symbols.
+          value.is_a?(Symbol) ? value.to_s : value
+        }
+      )
+    end
+
+    # Calling :flatten on an Array[self] will fail unless we override :to_ary to stop
+    # implicitly looking like an Array. Or we could implement :flatten, but this probably
+    # fixes other situations too.
+    # https://tenderlovemaking.com/2011/06/28/til-its-ok-to-return-nil-from-to_ary.html
+    def to_ary; nil; end
+
+    # Expose Liquid's 'assigns' accessors for any keys we weren't given upfront.
+    def method_missing(meth, *a)
+      # Grab the key from the method name, minus the trailing '=' for writers.
+      meth.to_s.end_with?('='.freeze) ? self[:assigns].store(meth.to_s.chomp('='.freeze).to_sym, a.first) : self[:assigns].fetch(meth, nil)
+    end
+
+    # Destination filename, or the element name.
+    def to_s; (self[:name] || self[:element]).to_s; end
+
+    # e.g. <ElementalCreation::source name=IIDX-turntable-full.svg, parents=[:anchor, :picture]>
+    def inspect; "<#{self.class.name.split('::'.freeze).last}::#{self[:element]} #{
+      [:name, :parents, :children].map { |k| (self[k].nil? || self[k]&.empty?) ? nil : " #{k.to_s}=#{self[k]}" }.compact.join(','.freeze)
+    }>"; end
+
+  end  # Struct ElementalCreation
+
+
+  # Wrap a Change in a Drop that emits Element attribute keys as well as the value.
+  # An underlying ChangeDrop will instantiate us as an instance variable
+  # and forward its Change to us, then return that instance from its own :attr method.
+  #
+  # Our templates can use this to avoid emitting empty attributes
+  # for corresponding empty values by calling {{ change.attr.whatever }}
+  # instead of invoking the regular ChangeDrop via {{ change.whatever }}.
+  #
+  # For example, if a <source>'s Change defines a media-query,
+  # {{ change.media }} will emit the plain value (e.g. `min-width: 800px`)
+  # and would typically be used in a template inside an explicit attribute key,
+  # e.g. `<source … media="{{ change.media }}"\>`.
+  #
+  # A template could instead call this drop via e.g. <source … {{ attr_media }}\>`
+  # to emit the same thing if a media-query is set but emit nothing if one isn't!
+  class ChangeAttrDrop < Liquid::Drop
+    def initialize(change)
+      @change = change
+    end
+    def liquid_method_missing(method)
+      # The underlying ChangeDrop is what responds to :attr, so we only
+      # need to respond to the Change keys in the same way ChangeDrop does.
+      value = @change&.send(method.to_sym)
+      # Return an empty String if there is no value, otherwise return `attr="value"`.
+      # Intentional leading-space in output so Liquid tags can abut in templates.
+      value.nil? ? ''.freeze : " #{method.to_str}=\"#{value.to_s}\""
+    end
+  end  # Struct ChangeAttrDrop
+
+
+  # Wrap a Change in a Drop that our Element Liquid::Templates can use
+  # to emit either values-alone or keys-and-values for any attribute
+  # of any one variation ot a media file.
+  class ChangeDrop < Liquid::Drop
+    def initialize(change)
+      @change = change
+    end
+    def initialism
+      @initialism ||= @change.type&.sub_type&.to_s.split(MIME::Type::SUB_TYPE_SEPARATORS)[0].upcase
+    end
+    def attr
+      # Use a ChangeAttrDrop to avoid emitting keys for empty values.
+      # It will respond to its own Change-key method just like we do.
+      @attr ||= Cooltrainer::ChangeAttrDrop.new(@change)
+    end
+    def liquid_method_missing(method)
+      # Liquid will send us String keys only, so translate them
+      # to Symbols when looking up in the Change Struct.
+      # Don't explicitly call :to_s before returning,
+      # because we might be returning an Array.
+      @change&.send(method.to_sym) || super
+    end
+  end  # Struct ChangeDrop
+
+end

data/lib/distorted-jekyll/liquid_liquid/anchor.liquid

@@ -0,0 +1,5 @@
+<a>
+{%- for child in children %}
+  {{ child }}
+{%- endfor -%}
+</a>

data/lib/distorted-jekyll/liquid_liquid/anchor_inline.liquid

@@ -0,0 +1 @@
+<a href="{{ change.dir }}{{ change.name }}{{ fragment }}">{{ change.name }} [{{ change.initialism }}]</a>

data/lib/distorted-jekyll/liquid_liquid/embed.liquid

@@ -0,0 +1 @@
+<embed src="{{ change.dir }}{{ change.name }}{{ fragment }}"{{ change.attr.type }}{{ change.attr.width }}{{ change.attr.height }}/>

data/lib/distorted-jekyll/liquid_liquid/img.liquid

@@ -0,0 +1 @@
+<img src="{{ change.dir }}{{ change.name }}"{{ change.attr.alt }}{{ change.attr.title }}{{ change.attr.loading }}/>

data/lib/distorted-jekyll/liquid_liquid/object.liquid

@@ -0,0 +1,5 @@
+<object data="{{ change.dir }}{{ change.name }}{{ fragment }}"{{ change.attr.type }}{{ change.attr.width }}{{ change.attr.height }}>
+{%- for child in children %}
+  {{ child }}
+{%- endfor -%}
+</object>

data/lib/distorted-jekyll/liquid_liquid/picture.liquid

@@ -0,0 +1,15 @@
+{% assign img_child = nil -%}
+<picture>
+{% for child in children %}
+{%- assign test_img = child | slice: 1, 3 -%}
+{%- if test_img == 'img' -%}
+{%- assign img_child = child -%}
+{%- else -%}
+{{ child }}
+{%- endif -%}
+{%- endfor -%}
+{%- unless img_child -%}
+{%- assign img_child = '<img/>' -%}
+{%- endunless -%}
+  {{ img_child }}
+</picture>

data/lib/distorted-jekyll/liquid_liquid/picture.rb

@@ -0,0 +1,48 @@
+require 'distorted-jekyll/liquid_liquid'
+require 'distorted/modular_technology/vips/save'
+require 'distorted/media_molecule'
+
+module Jekyll; end
+module Jekyll::DistorteD; end
+module Jekyll::DistorteD::LiquidLiquid; end
+module Jekyll::DistorteD::LiquidLiquid::Picture
+
+
+  # Returns a CSS media query String for a full-size Image outer_limit allowing btowsers,
+  # to properly consider its <source> alongside any generated resized versions of the same Image.
+  # https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries
+  def self.full_size_media_query(change, vips_image)
+    # This is kinda hacky, but use the Setting loader to look for `:outer_limits`
+    # of this Type that are larger than this `vips_image` since we won't have visibility of
+    # other `changes` from this Class instance method.
+    larger_than_us = Jekyll::DistorteD::the_setting_sun(:outer_limits, *(change.type.settings_paths))
+      .map { |l| l.fetch(:width, nil)}       # Look for a :width key in every outer limit.
+      .compact                               # Discard any limits that don't define :width.
+      .keep_if { |w| w > vips_image.width }  # Discard any limits whose :width is smaller than us.
+    # Add an additional `max` constraint to the media query if this `vips_image`
+    # is not the largest one in the <picture>.
+    # This effectively makes this <source> useless since so few user-agents will ever
+    # have a viewport the exact pixel width of this image, but for our use case
+    # it's better to have a useless media query than no media query since it will
+    # make browsers pick a better variation than this one.
+    return "(min-width: #{vips_image.width}px)#{" and (max-width: #{vips_image.width}px)" unless larger_than_us.empty?}"
+  end
+
+  # Returns an anonymous method that generates a <source> tag for Image output Types.
+  def self.render_picture_source
+    @@render_picture_source = lambda { |change|
+      # Fill in missing CSS media queries for any original-size (tag == null) Change that lacks one.
+      if change.width.nil? and not change.type.sub_type.include?('svg'.freeze)
+        change.width = to_vips_image.width
+      end
+      Cooltrainer::ElementalCreation.new(:picture_source, change, parents: Array[:anchor, :picture])
+    }
+  end
+
+  # Lots of MediaMolecules will want to render image representations of various media_types,
+  # so define a render method once for every Vips-supported Type that can be included/shared.
+  Cooltrainer::DistorteD::IMPLANTATION(:OUTER_LIMITS, Cooltrainer::DistorteD::Technology::Vips::Save).each_key { |type|
+    define_method(type.distorted_template_method, Jekyll::DistorteD::LiquidLiquid::Picture::render_picture_source)
+  }
+
+end

data/lib/distorted-jekyll/liquid_liquid/picture_source.liquid

@@ -0,0 +1 @@
+<source srcset="{{ change.dir }}{{ change.basename }}{{ change.extname }}{% if change.width %} {{ change.width }}w{% endif %}{% for break_width in change.breaks %}, {{ change.dir }}{{ change.basename }}-{{ break_width }}{{ change.extname }} {{ break_width }}w{% endfor %}"{{ change.attr.type }}{{ change.attr.media }}/>

data/lib/distorted-jekyll/liquid_liquid/root.liquid

@@ -0,0 +1,5 @@
+<div class="{{ dan }}">
+{%- for child in children %}
+  {{ child }}
+{%endfor%}
+</div>

data/lib/distorted-jekyll/liquid_liquid/video.liquid

@@ -0,0 +1,5 @@
+<video controls>
+{% for child in children %}
+{{ child }}
+{%- endfor -%}
+</video>

data/lib/distorted-jekyll/liquid_liquid/video_source.liquid

@@ -0,0 +1 @@
+<source src="{{ change.dir }}{{ change.name }}"{{ change.attr.type }}{{ change.attr.media }}/>

data/lib/distorted-jekyll/md_injection.rb

@@ -0,0 +1,310 @@
+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 flatten_attributes(el, type = :img)
+        matched = {}
+
+        if el.is_a? Enumerable
+          # Support an Array of elements...
+          el.each {
+            |child| matched.merge!(flatten_attributes(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.merge!(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.merge!(flatten_attributes(child, type))
+            }
+          end
+        end
+        matched
+      end
+
+      # Geenerates a DistorteD Liquid tag String given a Hash of element attributes.
+      # Examples:
+      #   {% distorted rpg-ra11.nfo alt="HellMarch INTENSIFIES" title="C&C RA2:YR NoCD NFO" encoding="IBM437" crop="none" %}
+      #   {% distorted DistorteD.png alt="DistorteD logo" title="This is so cool" crop="none" loading="lazy" %}
+      # The :additional_defaults Hash contains attribute values to set
+      # iff those attributes have no user-given value.
+      def distorted(attributes, additional_defaults: {})
+        "{% distorted #{additional_defaults.transform_keys{ |k|
+          # We will end up with a Hash of String-keys and String-values,
+          # so make sure override-defaults are String-keyed too.
+          k.to_s
+        }.merge(attributes).select{ |k, v|
+          # Filter out empty values, e.g. from an unfilled title/alt field
+          # in a Markdown image.
+          not v.empty?
+        }.map{ |k, v|
+          k.to_s + '="'.freeze + v.to_s + '"'.freeze
+        }.join(' '.freeze)} %}"
+      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(
+            flatten_attributes(imgs.first),
+            additional_defaults: {:crop => '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(flatten_attributes(img))
+          }.join("\n")}\n{% enddistort %}"
+        end
+      end
+
+    end
+  end
+end