distorted-jekyll 0.5.4 → 0.7.0

data/README.md

@@ -1,19 +1,16 @@
-# Cooltrainer::DistorteD
+# Jekyll::DistorteD
 
-`DistorteD` is a multimedia framework for Jekyll websites.
-
-Right now this repo contains two Gems:
-- [`DistorteD-Jekyll`](https://rubygems.org/gems/distorted-jekyll) contains anything and everything that depends on Jekyll.
-- [`DistorteD-Ruby`](https://rubygems.org/gems/distorted) contains just the abstract media file format handling code. It's separate so I can use those functions in other contexts and/or easily replace the Ruby core if necessary.
+`DistorteD-Jekyll` is a multimedia framework for Jekyll websites.
 
 ## Motivation
 
-DD is my solution for displaying photos, videos, and other types of media on [cooltrainer.org](https://cooltrainer.org) due to my dissatisfaction with every other solution I could find.
+DistorteD is my solution for displaying photos, videos, and other types of media on [cooltrainer.org](https://cooltrainer.org) due to my dissatisfaction with every other solution I could find.
 
 My previous approach was similar to what's [described here](https://eduardoboucas.com/blog/2014/12/07/including-and-managing-images-in-jekyll.html), with small/medium/large image size variations generated with [Jekyll-MiniMagick](https://github.com/MattKevan/Jekyll-MiniMagick-new).
 
 Here are some already-existing ways to put pictures on your Jekyll site that are worth your consideration before choosing DistorteD:
 
+- Octopress' [image_tag](https://github.com/imathis/octopress/blob/master/plugins/image_tag.rb) plugin.
 - [jekyll-responsive-image](https://github.com/wildlyinaccurate/jekyll-responsive-image)
 - [jekyll_picture_tag](https://rbuchberger.github.io/jekyll_picture_tag/)
 - [jekyll-gallery-generator](https://github.com/ggreer/jekyll-gallery-generator)
@@ -95,7 +92,7 @@ will be transformed into.
 %}
 ```
 
-Or, for a DD grid:
+or, for a DD grid:
 
 ```
 {% distort %}
@@ -157,11 +154,10 @@ Clone the DistorteD repository and modify your Jekyll `Gemfile` to refer to your
 
 ```
 gem 'distorted-jekyll', :path => '~/repos/DistorteD/DistorteD-Jekyll/'[, :branch => 'NEW-SENSATION']
-gem 'distorted', :path => '~/repos/DistorteD/DistorteD-Ruby/'[, :branch => 'NEW-SENSATION']
 ```
 
-The `DistorteD-Jekyll` Gem will automatically use its local sibling `DistorteD-Ruby` Gem if used in this way.
+The `DistorteD-Jekyll` Gem will automatically use its local sibling `DistorteD-Floor` Gem if used in this way.
 
 ## License
 
-DistorteD is available as open source under the terms of the [GNU Affero General Public License version 3](https://opensource.org/licenses/AGPL-3.0).
+The gem is available as open source under the terms of the [GNU Affero General Public License version 3](https://opensource.org/licenses/AGPL-3.0).

data/lib/distorted-jekyll.rb

@@ -0,0 +1,75 @@
+require 'distorted-jekyll/13th-style'
+require 'distorted-jekyll/blocks'
+require 'distorted-jekyll/md_injection'
+require 'distorted-jekyll/invoker'
+
+
+FATAL_FURY = true
+UPDATE_RUBY = "Please use DistorteD with Ruby 2.7.0 or later"
+def update_ruby
+  if defined? RUBY_PLATFORM
+    if (/freebsd/ =~ RUBY_PLATFORM) != nil
+      return 'pkg install lang/ruby27'
+    elsif (/darwin/ =~ RUBY_PLATFORM) != nil
+      return 'brew upgrade ruby'
+    elsif (/win/ =~ RUBY_PLATFORM) != nil
+      return 'https://rubyinstaller.org/'
+    elsif (/linux/ =~ RUBY_PLATFORM) != nil
+      if File.exists?('/etc/lsb-release')
+        lsb = File.read('/etc/lsb-release')
+        if (/Ubuntu|LinuxMint/ =~ lsb) != nil
+          return 'https://www.brightbox.com/docs/ruby/ubuntu/#installation'
+        end
+      end
+    end
+  end
+  return 'https://github.com/rbenv/ruby-build'
+end
+
+
+# I want to be able to use:
+# - Array#dig and Hash#dig (Ruby 2.3): https://bugs.ruby-lang.org/issues/11643
+# - Lonely operator (Ruby 2.3): https://bugs.ruby-lang.org/issues/11537
+# - Hash#transform_keys (Ruby 2.5): https://bugs.ruby-lang.org/issues/13583
+# - Enumerable#filter_map (Ruby 2.7): https://bugs.ruby-lang.org/issues/5663
+#     https://blog.saeloun.com/2019/05/25/ruby-2-7-enumerable-filter-map.html
+# - 'Real' kwargs in preparation for Ruby 3: https://bugs.ruby-lang.org/issues/14183
+#     https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/
+if [
+  Hash.method_defined?(:dig),  # 2.3
+  Hash.method_defined?(:transform_keys),  # 2.5
+  Enumerable.method_defined?(:filter_map),  # 2.7
+].all?
+  # Monkey-patch Jekyll::Cleaner to not nuke DistorteD-generated variations
+  # for our media files. This makes DistorteD fast!
+  require 'distorted-jekyll/monkey_business/jekyll/cleaner'
+
+  # Register DistorteD's entrypoint class with Liquid.
+  # `Invoker` will mix in the proper handler module for the given media.
+  Liquid::Template.register_tag('distorted', Jekyll::DistorteD::Invoker)
+
+  # Register a block version for arranging multiple pieces of media.
+  Liquid::Template.register_tag('distort', Jekyll::DistorteD::BLOCKS)
+
+  # Register a tag for basic DistorteD CSS.
+  Liquid::Template.register_tag('13th_style', Jekyll::DistorteD::ThirteenthStyle)
+
+  # Transform Markdown image syntax ![alt](url.jpg "title")
+  # to instances of our liquid tag {% distorted %}
+  # Available hooks can be seen here:
+  #   https://github.com/jekyll/jekyll/blob/master/lib/jekyll/hooks.rb
+  # `:documents` does not seem to include `_pages` but does include `_posts`.
+  Jekyll::Hooks.register(:pages, :pre_render, &md_injection)
+  Jekyll::Hooks.register(:posts, :pre_render, &md_injection)
+
+else
+  # Example of how this looks with the outdated Ruby 2.5 on my Mint 19 laptop:
+  #
+  # Bundler::GemRequireError: There was an error while trying to load the gem 'distorted-jekyll'.
+  # Gem Load Error is: Please use DistorteD with Ruby 2.7.0 or later: https://www.brightbox.com/docs/ruby/ubuntu/#installation
+  if FATAL_FURY
+    raise RuntimeError.new("#{UPDATE_RUBY}: #{update_ruby}")
+  else
+    Jekyll.logger.info('DistorteD', "#{UPDATE_RUBY}: #{update_ruby}")
+  end
+end

data/lib/distorted-jekyll/13th-style.css

@@ -0,0 +1,79 @@
+div.distorted {text-align: center;}
+div.distorted::after {
+    content: '';
+    display: block;
+    clear: left;
+}
+div.distorted.svg {background-color: #fbfbf8;}
+div.distorted.pdf > object {min-height: 76vh;}
+div.distorted > video {object-fit: contain;}
+div.distorted-caption {
+    color: #8888888;
+    margin-top: 0.5em;
+}
+div.distorted-block {
+    width: 100%;
+    clear: both;
+}
+div.distorted-block > div.distorted {
+    display: block;
+    box-sizing: border-box;
+    float: left;
+    border: 4px solid transparent;
+    margin: 0px;
+    text-align: center;
+    width: 100%;
+}
+@media screen and (min-width: 40em) {
+  div.distorted-block > div.distorted {
+    width: 50%;
+  }
+  div.distorted-block > div.distorted:only-child {
+    width: 100%;
+  }
+  div.distorted-block > div.distorted:first-child:nth-last-child(3),
+  div.distorted-block > div.distorted:first-child:nth-last-child(3) ~ div.distorted,
+  div.distorted-block > div.distorted:first-child:nth-last-child(6),
+  div.distorted-block > div.distorted:first-child:nth-last-child(6) ~ div.distorted,
+  div.distorted-block > div.distorted:first-child:nth-last-child(9),
+  div.distorted-block > div.distorted:first-child:nth-last-child(9) ~ div.distorted {
+    width: 33.3333%;
+  }
+  div.distorted-block > div.distorted:first-child:nth-last-child(5),
+  div.distorted-block > div.distorted:first-child:nth-last-child(5) ~ div.distorted:nth-child(2) {
+    width: 50%;
+  }
+  div.distorted-block > div.distorted:first-child:nth-last-child(5) ~ div.distorted {
+    width: 33.3333%;
+  }
+  div.distorted-block > div.distorted:first-child:nth-last-child(7) ~ div.distorted:nth-child(3),
+  div.distorted-block > div.distorted:first-child:nth-last-child(7) ~ div.distorted:nth-child(4),
+  div.distorted-block > div.distorted:first-child:nth-last-child(7) ~ div.distorted:nth-child(5) {
+    width: 33.3333%;
+  }
+}
+@media screen and (min-width: 76em) {
+  div.distorted-block > div.distorted:first-child:nth-last-child(4),
+  div.distorted-block > div.distorted:first-child:nth-last-child(4) ~ div.distorted,
+  div.distorted-block > div.distorted:first-child:nth-last-child(8),
+  div.distorted-block > div.distorted:first-child:nth-last-child(8) ~ div.distorted {
+    width: 25%;
+  }
+  div.distorted-block > div.distorted:first-child:nth-last-child(5),
+  div.distorted-block > div.distorted:first-child:nth-last-child(5) ~ div.distorted:nth-child(2),
+  div.distorted-block > div.distorted:first-child:nth-last-child(5) ~ div.distorted,
+  div.distorted-block > div.distorted:first-child:nth-last-child(10),
+  div.distorted-block > div.distorted:first-child:nth-last-child(10) ~ div.distorted {
+    width: 20%;
+  }
+  div.distorted-block > div.distorted:first-child:nth-last-child(7),
+  div.distorted-block > div.distorted:first-child:nth-last-child(7) ~ div.distorted:nth-child(2),
+  div.distorted-block > div.distorted:first-child:nth-last-child(7) ~ div.distorted:nth-child(3) {
+    width: 33.3333%;
+  }
+  div.distorted-block > div.distorted:first-child:nth-last-child(7) ~ div.distorted,
+  div.distorted-block > div.distorted:first-child:nth-last-child(7) ~ div.distorted:nth-child(4),
+  div.distorted-block > div.distorted:first-child:nth-last-child(7) ~ div.distorted:nth-child(5) {
+    width: 25%;
+  }
+}

data/lib/distorted-jekyll/13th-style.rb

@@ -0,0 +1,58 @@
+
+# Slip in and out of phenomenon
+require 'liquid/tag'
+require 'liquid/tag/parser'
+
+# Explicitly required for l/t/parser since a1cfa27c27cf4d4c308da2f75fbae88e9d5ae893
+require 'shellwords'
+
+
+module Jekyll
+  module DistorteD
+    class ThirteenthStyle < Liquid::Tag
+
+      TAB_SEQUENCE = '  '.freeze  # two spaces
+
+      def initialize(tag_name, arguments, liquid_options)
+        super
+
+        # 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)
+
+        # Specify how many levels to indent printed output.
+        # Indentation will apply to all lines after the first,
+        # because the first line's output will fall at the same
+        # place as our Liquid tag invocation.
+        @tabs = parsed_arguments[:tabs] || 0
+      end
+
+      # This is going to go away in a future Liquid version
+      # and render_to_output_buffer will be the standard approach.
+      # I'm going ahead and using it since we are building strings here.
+      def render(context)
+        return render_to_output_buffer(context, '')
+      end
+
+      def render_to_output_buffer(context, output)
+        css_filename = File.join(File.dirname(__FILE__), '13th-style.css'.freeze)
+
+        # Use IO.foreach() to call a block on each line of our template file
+        # without slurping the entire file into memory like File.read() / File.readlines()
+        File.foreach(css_filename).with_index do |line, line_num|
+          # Don't indent the first line of the CSS file, because the first line
+          # will print starting at the position of our {% 13thStyle %} Liquid tag.
+          unless line_num == 0
+            output << TAB_SEQUENCE * @tabs
+          end
+          output << line
+        end
+        # Remove CSS comments from output so I can leave notes there
+        # without bloating up my output.
+        # Based on C-shebang-style comment regex from MRE3
+        return output.gsub(/\/\*[^*]*\*+(?:[^*\/][^*]*\*+)*\//, '')
+      end
+
+    end  # ThirteenthStyle
+  end  # DistorteD
+end  # Jekyll

data/lib/distorted-jekyll/_config_default.yml

@@ -0,0 +1,63 @@
+# Override any or all of this default configuration in your Jekyll site's `_config.yml`!
+
+# Is it possible to do a Set of Hashes using the Set syntax in YAML?
+# It works with the Array syntax, so that's what I'm using here,
+# but keep in mind any Arrays will be converted to Sets when loaded,
+# so duplicate Array values will be compacted!
+
+standard_image: &standard_image
+  - crop: none
+    breaks: [333, 555, 777, 1111]
+
+distorted:
+
+  # Should unrecognized media-types fall back to a bare
+  # <img> tag around the original media file?
+  # If not, the site build will fail when an unrecognized
+  # file is encountered.
+  never_let_you_down: true
+
+  # Configure DistorteD format changes by media_type, then by sub_type.
+  # The list of target formats is plain text, media_type/sub_type.
+  # These are mostly based on IANA's official Media Types list:
+  # https://www.iana.org/assignments/media-types/media-types.xhtml
+  # but with some custom additions like using 'gif-sequence' for
+  # animated GIF and leaving 'image/gif' to refer to single-frame GIFs.
+  changes:
+    image:
+      jpeg:
+        ? image/jpeg
+        ? image/webp
+      png:
+        ? image/png
+        ? image/webp
+      gif:
+        ? image/gif
+        ? image/png
+        ? image/webp
+      gif-sequence:
+        ? image/gif-sequence
+      svg:
+        ? image/svg+xml
+        ? image/png
+        ? image/webp
+    text:
+      plain:
+        ? text/plain
+        ? image/png
+        ? image/webp
+      x-nfo:
+        ? text/x-nfo
+        ? image/png
+        ? image/webp
+    font:
+      ttf:
+        ? font/ttf
+        ? image/png
+        ? image/webp
+
+  outer_limits:
+    image:
+      jpeg: *standard_image
+      png: *standard_image
+      webp: *standard_image

data/lib/distorted-jekyll/blocks.rb

@@ -0,0 +1,16 @@
+
+module Jekyll
+  module DistorteD
+    class BLOCKS < Liquid::Block
+
+      def initialize(tag_name, arguments, liquid_options)
+        super
+      end
+
+      def render(context)
+        "<div class=\"distorted-block\">#{super}</div>"
+      end
+
+    end  # BLOCKS
+  end  # DistorteD
+end  # Jekyll

data/lib/distorted-jekyll/invoker.rb

@@ -0,0 +1,234 @@
+# Our custom Exceptions
+require 'distorted/error_code'
+
+# Molecule loading and plugging functionality
+require 'distorted/invoker'
+
+# MIME::Typer
+require 'distorted/checking_you_out'
+
+# Configuration-loading code
+require 'distorted-jekyll/the_setting_sun'
+require 'distorted-jekyll/static_state'
+
+# Slip in and out of phenomenon
+require 'liquid/tag'
+require 'liquid/tag/parser'
+require 'distorted-jekyll/liquid_liquid'
+
+require 'distorted-jekyll/media_molecule'
+
+# Explicitly required for l/t/parser since a1cfa27c27cf4d4c308da2f75fbae88e9d5ae893
+require 'shellwords'
+
+# Set is in stdlib but is not in core.
+require 'set'
+# Set.to_hash
+require 'distorted/monkey_business/set'
+
+# I mean, this is why we're here, right?
+require 'jekyll'
+
+
+class Jekyll::DistorteD::Invoker < Liquid::Tag
+
+  GEM_ROOT = File.dirname(__FILE__).freeze
+
+  include Jekyll::DistorteD::Setting       # Config-loading methods.
+  include Jekyll::DistorteD::StaticState   # Jekyll::StaticFile impersonation methods.
+  include Cooltrainer::DistorteD::Invoker  # Instance-setup methods.
+
+
+  # 𝘏𝘖𝘞 𝘈𝘙𝘌 𝘠𝘖𝘜 𝘎𝘌𝘕𝘛𝘓𝘌𝘔𝘌𝘕 ！！
+  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.delete(:src)
+    else
+      @name = parsed_arguments.delete(:argv1)
+    end
+
+    # Load contextual variables for abstract()
+    @tag_arguments = parsed_arguments.select{ |attr, val|
+      not [nil, ''.freeze].include?(val)
+    }.transform_keys(&:to_sym).transform_values { |val|
+      case val
+      when 'true' then true
+      when 'false' then false
+      when String then (val.length <= Jekyll::DistorteD::ARBITRARY_ATTR_SYMBOL_STRING_LENGTH_BOUNDARY) ? val.to_sym : val.freeze
+      else val
+      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
+
+  end
+
+  # Returns a Set of DD MIME::Types descriving our file,
+  # optionally falling through to a plain file copy.
+  def type_mars
+    @type_mars ||= (CHECKING::YOU::OUT(path, so_deep: true) & lower_world.keys.to_set).tap { |gemini|
+      if gemini.empty? && the_setting_sun(:never_let_you_down)
+        gemini << CHECKING::YOU::OUT['application/x.distorted.never-let-you-down']
+      end
+    }
+    raise MediaTypeNotImplementedError.new(@name) if @type_mars.empty?
+    @type_mars
+  end
+
+  # Returns an Array[Change] for every intended output Type
+  # and every variation (e.g. resolution, bitrate) on each Type.
+  def changes
+    # The available/desired output Media Types and (variations on those Types)
+    # are based on the input Type and the Molecule(s) available to service those Types.
+    # Use an Array, since order might be important here when generating many variations
+    # at multiple levels of the DistorteD stack, e.g. the actual files on the Floor level
+    # and the templates/markup here in the Jekyll level.
+    @changes ||= type_mars.each_with_object(Array[]) { |lower, wanted|
+      # Query our configuration for Type changes, e.g. image/webp to (image/png and image/webp).
+      # Handle empty sub_types by compacting and splatting a sub-Array.
+      change_config = the_setting_sun(:changes, *(lower.settings_paths))
+      # If there is no config, treat it as a change to the same Type as the input,
+      # otherwise instantiate each "mediatype/subtype" config String to a MIME::Type.
+      ((change_config.nil? || change_config&.empty?) ? Set[lower] : change_config.map {|t| CHECKING::YOU::OUT[t]}).each { |type|
+        # Query our configuration again for variations on each Type.
+        # For example, one single image Type may want multiple resolutions to enable responsive <picture> tags,
+        # or a single video Type may want multiple bitrates for adaptive streaming.
+        limit_breaks = the_setting_sun(:outer_limits, *(type&.settings_paths)) || Array[Hash[]]
+        # Which MediaMolecule Modules support this Type as an output? Probably just one.
+        outer_limits.keep_if { |k, v| v.has_key?(type) }.keys.each { |molecule|
+          # As before, if there is nothing in the config just treat it as a Change to
+          # the full resolution/bitrate/whatever as the input, so this will always run at least once.
+          limit_breaks.each { |limit_break|
+            # Merge each variation's config with any/all attributes given to our Liquid Tag,
+            # as well as any Jekyll Stuff™ like the relative destination path.
+            change_arguments = limit_break.merge(Hash[:dir => @relative_dest]).merge(context_arguments)
+            # Each Change will carry instance Compound data in Atom Structs so we can avoid modifying
+            # the Compound Struct with any variation-specific values since they will be reused.
+            atoms = Hash.new
+            # We will always want an Atom from every Compound even if it only carries the :default.
+            Cooltrainer::DistorteD::IMPLANTATION(:OUTER_LIMITS, molecule)&.dig(type)&.each_pair { |aka, compound|
+              next if aka != compound.element  # Skip alias Compounds since they will all be handled at once.
+              # Look for a user-given argument matching any supported alias of a Compound,
+              # and check those values against the Compound for validity.
+              atoms.store(compound.element, Cooltrainer::Atom.new(compound.isotopes.reduce(nil) { |value, isotope|
+                # TODO: valid?
+                value || change_arguments&.delete(isotope)
+              }, compound.default))
+            }
+            # After looping through the Compounds and calling :delete for matched values,
+            # this bag will be left with only the freeform non-Compound-associated arguments, if any.
+            # Separate those into arguments that match Change member names, and arguments that don't.
+            change_member_keys, atom_keys = change_arguments.keys.partition(&Cooltrainer::Change.members.method(:include?))
+            # Instantiate a no-default Atom for every remaining argument that isn't a Change member.
+            atom_keys.each { |attribute| atoms.store(attribute, Cooltrainer::Atom.new(change_arguments.delete(attribute), nil)) }
+            # Instantiate each variation of each Type into a Change struct
+            # that will handle some of the details like output-filename generation.
+            wanted.append(Cooltrainer::Change.new(type, src: @name, molecule: molecule, **change_arguments, **atoms))
+          }
+        }
+      }
+      wanted
+    }
+  end
+
+  # Return any arguments given by the user to our Liquid tag.
+  # This method name is generic across all DD entrypoints so it can be
+  # referenced from lower layers in the pile.
+  def context_arguments
+    @tag_arguments ||= Hash[]
+  end
+
+  # Returns a context-only setting from our Liquid attributes.
+  def abstract(key)
+    context_arguments.dig(key)
+  end
+
+  # Called by Jekyll::Renderer
+  # https://github.com/jekyll/jekyll/blob/HEAD/lib/jekyll/renderer.rb
+  # https://jekyllrb.com/tutorials/orderofinterpretation/
+  def render(context)
+    # 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.
+    @relative_dest = page_data['url'.freeze]
+    unless @relative_dest[-1] == Jekyll::DistorteD::PATH_SEPARATOR
+      @relative_dest = File.dirname(@relative_dest)
+      # Append the trailing slash so we don't have to do it
+      # in the Liquid templates.
+      @relative_dest << Jekyll::DistorteD::PATH_SEPARATOR
+    end
+
+    # Add our new file to the list that will be handled
+    # by Jekyll's built-in StaticFile generator.
+    @site.static_files << self
+    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)
+    roots_of_my_way = Cooltrainer::ElementalCreation.new(:root).tap { |wrapper|
+      wrapper.dan = "distorted #{changes.reduce(Set[]) { |classes, change|
+        classes.add(change.molecule&.name.split('::'.freeze).last.downcase)
+        classes.add(change.type.sub_type.to_s.split(MIME::Type::SUB_TYPE_SEPARATORS)[0])
+      }.to_a.join(' ')}"
+    }
+
+    changes&.each { |change|
+      unless self.respond_to_missing?(change.type.distorted_template_method)
+        Jekyll.logger.error(@name, "Missing template method #{change.type.distorted_template_method}")
+        raise MediaTypeOutputNotImplementedError.new(@name, type_mars, self.class.name)
+      end
+      Jekyll.logger.debug("DistorteD::#{change.type.distorted_template_method}", File.join(change.dir, change.name))
+
+      # Get an ElementalCreation Struct from the MediaMolecule's render method.
+      # WISHLIST: Remove the empty final positional Hash argument once we require a Ruby version
+      # that will not perform the implicit Change-to-Hash conversion due to Change's
+      # implementation of :to_hash. Ruby 2.7 will complain but still do the conversion,
+      # breaking downstream callers that want a Struct they can call arbitrary key methods on.
+      # https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/
+      roots_of_my_way.mad_child(self.send(change.type.distorted_template_method, change, **{}))
+    }
+
+    output << roots_of_my_way.render
+  end
+
+end