distorted-jekyll 0.5.4 → 0.7.0

data/lib/distorted-jekyll/media_molecule.rb

@@ -0,0 +1,20 @@
+require 'set'
+require 'distorted/media_molecule'
+
+module Jekyll::DistorteD
+  # Load Jekyll Molecules which will implicitly also load
+  # the Floor Molecules they're based on if they aren't already.
+  @@loaded_molecules rescue begin
+    Dir[File.join(__dir__, 'media_molecule', '*.rb')].each { |molecule| require molecule }
+    @@loaded_molecules = true
+  end
+end
+
+module Cooltrainer::DistorteD
+  # Override default Molecule Set with their Liquid-rendering submolecules.
+  def self.media_molecules
+    Jekyll::DistorteD::Molecule.constants.map { |molecule|
+      Jekyll::DistorteD::Molecule::const_get(molecule)
+    }.to_set
+  end
+end

data/lib/distorted-jekyll/media_molecule/font.rb

@@ -0,0 +1,21 @@
+require 'set'
+
+require 'distorted/media_molecule/font'
+require 'distorted-jekyll/liquid_liquid/picture'
+
+
+module Jekyll; end
+module Jekyll::DistorteD; end
+module Jekyll::DistorteD::Molecule; end
+module Jekyll::DistorteD::Molecule::Font
+
+  include Cooltrainer::DistorteD::Molecule::Font
+  include Jekyll::DistorteD::LiquidLiquid::Picture
+
+  Cooltrainer::DistorteD::IMPLANTATION(:LOWER_WORLD, Cooltrainer::DistorteD::Molecule::Font).each_key { |type|
+    define_method(type.distorted_template_method) { |change|
+      Cooltrainer::ElementalCreation.new(:anchor_inline, change, **{})
+    }
+  }
+
+end

data/lib/distorted-jekyll/media_molecule/image.rb

@@ -0,0 +1,15 @@
+require 'set'
+
+require 'distorted-jekyll/liquid_liquid/picture'
+require 'distorted/media_molecule/image'
+
+
+module Jekyll; end
+module Jekyll::DistorteD; end
+module Jekyll::DistorteD::Molecule; end
+module Jekyll::DistorteD::Molecule::Image
+
+  include Cooltrainer::DistorteD::Molecule::Image
+  include Jekyll::DistorteD::LiquidLiquid::Picture
+
+end

data/lib/distorted-jekyll/media_molecule/never_let_you_down.rb

@@ -0,0 +1,28 @@
+require 'set'
+
+require 'distorted/checking_you_out'
+require 'distorted-jekyll/liquid_liquid'
+
+module Jekyll; end
+module Jekyll::DistorteD; end
+module Jekyll::DistorteD::Molecule; end
+module Jekyll::DistorteD::Molecule::NeverLetYouDown
+
+  FALLBACK_TYPE = CHECKING::YOU::OUT['application/x.distorted.never-let-you-down']
+  LOWER_WORLD = Hash[
+    FALLBACK_TYPE => Hash[
+      :alt => Cooltrainer::Compound.new(:alt, blurb: 'Alternate text to display when this element cannot be rendered.'),
+      :title => Cooltrainer::Compound.new(:title, blurb: 'Extra information about this element — usually displayed as tooltip text.'),
+      :href => Cooltrainer::Compound.new(:href, blurb: 'Hyperlink reference for this element.')
+    ]
+  ]
+  OUTER_LIMITS = Hash[FALLBACK_TYPE => nil]
+
+  define_method(FALLBACK_TYPE.distorted_file_method) { |dest_root, change|
+    copy_file(change.path(dest_root))
+  }
+  define_method(FALLBACK_TYPE.distorted_template_method) { |change|
+    Cooltrainer::ElementalCreation.new(:anchor_inline, change, **{})
+  }
+
+end

data/lib/distorted-jekyll/media_molecule/pdf.rb

@@ -0,0 +1,108 @@
+require 'set'
+
+require 'distorted/media_molecule/pdf'
+
+
+module Jekyll; end
+module Jekyll::DistorteD; end
+module Jekyll::DistorteD::Molecule; end
+module Jekyll::DistorteD::Molecule::PDF
+
+  include Cooltrainer::DistorteD::Molecule::PDF
+
+  # https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/pdf_open_parameters.pdf
+  #
+  # Adobe's PDF Open Parameters documentation sez:
+  # "Individual parameters, together with their values (separated by & or #),
+  # can be no greater then 32 characters in length."
+  # …but then goes on to show some examples (like `comment`)
+  # that are clearly longer than 32 characters.
+  # Dunno. I'll err on the side of giving you a footgun.
+  #
+  # Keep the PDF Open Params in the order they are defined
+  # in the Adobe documentation, since it says they should
+  # be specified in the URL in that same order.
+  #
+  # "You cannot use the reserved characters =, #, and &.
+  # There is no way to escape these special characters."
+  RESERVED_CHARACTERS_FRAGMENT = '[^=#&]+'.freeze
+  FLOAT_INT_FRAGMENT = '[+-]?([0-9]+([.][0-9]*)?|[.][0-9]+)'.freeze
+  ZERO_TO_ONE_HUNDRED = /^(([1-9]\d?|1\d{1})([.,]\d{0,1})?|100([.,]0{1})?)$/
+  PDF_OPEN_PARAMS = Array[
+    Cooltrainer::Compound.new(:nameddest, valid: /^#{RESERVED_CHARACTERS_FRAGMENT}$/, blurb: 'Jump to a named destination in the document.'),
+    Cooltrainer::Compound.new(:page, valid: Integer, default: 1, blurb: 'Jump to a numbered page in the document.'),
+    Cooltrainer::Compound.new(:comment, valid: /^#{RESERVED_CHARACTERS_FRAGMENT}$/, blurb: 'Jump to a comment on a given page.'),
+    Cooltrainer::Compound.new(:collab, valid: /^(DAVFDF|FSFDF|DB)@#{RESERVED_CHARACTERS_FRAGMENT}$/, blurb: 'Sets the comment repository to be used to supply and store comments for the document.'),
+    Cooltrainer::Compound.new(:zoom, valid: /^#{FLOAT_INT_FRAGMENT}(,#{FLOAT_INT_FRAGMENT},#{FLOAT_INT_FRAGMENT})?$/, blurb: 'Sets the zoom and scroll factors, using float or integer values.'),
+    Cooltrainer::Compound.new(:view, valid: /^Fit(H|V|B|BH|BV(,#{FLOAT_INT_FRAGMENT})?)?$/, default: :Fit, blurb: 'Set the view of the displayed page, using the keyword values defined in the PDF language specification. For more information, see the PDF Reference.'),
+    Cooltrainer::Compound.new(:viewrect, valid: /^#{FLOAT_INT_FRAGMENT},#{FLOAT_INT_FRAGMENT},#{FLOAT_INT_FRAGMENT},#{FLOAT_INT_FRAGMENT}$/, blurb: 'Sets the view rectangle using float or integer values in a coordinate system where 0,0 represents the top left corner of the visible page, regardless of document rotation.'),
+    Cooltrainer::Compound.new(:pagemode, valid: Set[:none, :thumbs, :bookmarks], default: :none, blurb: 'Displays bookmarks or thumbnails.'),
+    Cooltrainer::Compound.new(:scrollbar, valid: Cooltrainer::BOOLEAN_VALUES, default: true, blurb: 'Turns scrollbars on or off.'),
+    Cooltrainer::Compound.new(:search, valid: /^#{RESERVED_CHARACTERS_FRAGMENT}(,\s#{RESERVED_CHARACTERS_FRAGMENT})*$/ , blurb: 'Opens the Search panel and performs a search for any of the words in the specified word list. The first matching word is highlighted in the document.'),
+    Cooltrainer::Compound.new(:toolbar, valid: Cooltrainer::BOOLEAN_VALUES, default: true, blurb: 'Turns the toolbar on or off.'),
+    Cooltrainer::Compound.new(:statusbar, valid: Cooltrainer::BOOLEAN_VALUES, default: true, blurb: 'Turns the status bar on or off.'),
+    Cooltrainer::Compound.new(:messages, valid: Cooltrainer::BOOLEAN_VALUES, default: false, blurb: 'Turns the document message bar on or off.'),
+    Cooltrainer::Compound.new(:navpanes, valid: Cooltrainer::BOOLEAN_VALUES, default: true, blurb: 'Turns the navigation panes and tabs on or off.'),
+    Cooltrainer::Compound.new(:highlight, valid: /^#{FLOAT_INT_FRAGMENT},#{FLOAT_INT_FRAGMENT},#{FLOAT_INT_FRAGMENT},#{FLOAT_INT_FRAGMENT}$/, blurb: 'Highlights a specified rectangle on the displayed page. Use the `page` command before this command.'),
+    Cooltrainer::Compound.new(:fdf, valid: /^#{RESERVED_CHARACTERS_FRAGMENT}$/, blurb: 'Specifies an FDF file to populate form fields in the PDF file being
+opened.'),
+  ]
+
+  # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/object#Attributes
+  CONTAINER_ATTRIBUTES = Array[
+    Cooltrainer::Compound.new(:alt, valid: String),
+    Cooltrainer::Compound.new(:caption, valid: String),
+    Cooltrainer::Compound.new(:height,  valid: String, default: '100%'.freeze, blurb: '<object> viewer container height.'),
+    Cooltrainer::Compound.new(:width,  valid: String, default: '100%'.freeze, blurb: '<object> viewer container width.'),
+  ]
+
+  OUTER_LIMITS = Hash[
+    CHECKING::YOU::OUT['application/pdf'] => PDF_OPEN_PARAMS.concat(CONTAINER_ATTRIBUTES).reduce(Hash[]) {|aka, compound|
+      aka.tap { |a| a.store(compound.element, compound) }
+    }
+  ]
+
+  # Generate a Hash of our PDF Open Params based on any given to the Liquid tag
+  # and any loaded from the defaults.
+  # https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/pdf_open_parameters.pdf
+  def pdf_open_params
+    PDF_OPEN_PARAMS.reduce(Hash[]) {|params, compound|
+      # Only include those params whose user-given value exists and differs from its default.
+      params.tap { |p|
+        p.store(compound.element, abstract(compound.element)) unless [
+          nil, ''.freeze, compound.default,
+        ].include?(abstract(compound.element))
+      }
+    }
+  end
+
+  # Generate the URL fragment version of the PDF Open Params.
+  # This would be difficult / impossible to construct within Liquid
+  # from the individual variables, so let's just do it out here.
+  def pdf_open_params_url
+    pdf_open_params.map{ |(k,v)|
+      case
+      when k == :search
+        # The PDF Open Params docs specify `search` should be quoted.
+        "#{k}=\"#{v}\""
+      when Cooltrainer::BOOLEAN_VALUES.include?(v)
+        # Convert booleans to the numeric representation Adobe use here.
+        "#{k}=#{v ? 1 : 0}"
+      else
+        "#{k}=#{v}"
+      end
+    }.join('&')
+  end
+
+  # http://joliclic.free.fr/html/object-tag/en/
+  # TODO: iOS treats our <object> like an <img>,
+  # showing only the first page with transparency and stretched to the
+  # size of the container element.
+  # We will need something like PDF.js in an <iframe> to handle this.
+  define_method(CHECKING::YOU::OUT['application/pdf'].distorted_template_method) { |change|
+    Cooltrainer::ElementalCreation.new(:object, change, children: [:embed, :anchor_inline]).tap { |e|
+      e.fragment = pdf_open_params.empty? ? ''.freeze : "##{pdf_open_params_url}"
+    }
+  }
+
+end  # PDF

data/lib/distorted-jekyll/media_molecule/svg.rb

@@ -0,0 +1,20 @@
+require 'set'
+
+require 'distorted/media_molecule/svg'
+require 'distorted-jekyll/liquid_liquid/picture'
+
+
+module Jekyll; end
+module Jekyll::DistorteD; end
+module Jekyll::DistorteD::Molecule; end
+module Jekyll::DistorteD::Molecule::SVG
+
+  include Cooltrainer::DistorteD::Molecule::SVG
+  include Jekyll::DistorteD::LiquidLiquid::Picture
+
+  define_method(
+    CHECKING::YOU::OUT['image/svg+xml'].distorted_template_method,
+    Jekyll::DistorteD::LiquidLiquid::Picture::render_picture_source,
+  )
+
+end

data/lib/distorted-jekyll/media_molecule/text.rb

@@ -0,0 +1,23 @@
+require 'set'
+
+require 'distorted/media_molecule/text'
+require 'distorted-jekyll/liquid_liquid/picture'
+
+
+module Jekyll; end
+module Jekyll::DistorteD; end
+module Jekyll::DistorteD::Molecule; end
+module Jekyll::DistorteD::Molecule::Text
+
+  include Cooltrainer::DistorteD::Molecule::Text
+  include Jekyll::DistorteD::LiquidLiquid::Picture
+
+  Cooltrainer::DistorteD::IMPLANTATION(:LOWER_WORLD, Cooltrainer::DistorteD::Molecule::Text).each_key { |type|
+    define_method(type.distorted_template_method) { |change|
+      # Remove the destructured empty Hash once we drop Ruby 2.7
+      # so we don't get auto-destructured due to Change#to_hash.
+      Cooltrainer::ElementalCreation.new(:anchor_inline, change, **{})
+    }
+  }
+
+end  # Text

data/lib/distorted-jekyll/media_molecule/video.rb

@@ -0,0 +1,45 @@
+require 'distorted/media_molecule/video'
+
+
+module Jekyll; end
+module Jekyll::DistorteD; end
+module Jekyll::DistorteD::Molecule; end
+module Jekyll::DistorteD::Molecule::Video
+
+  include Cooltrainer::DistorteD::Molecule::Video
+
+  Cooltrainer::DistorteD::IMPLANTATION(:LOWER_WORLD, Cooltrainer::DistorteD::Molecule::Video).each_key { |type|
+    define_method(type.distorted_template_method) { |change|
+      Cooltrainer::ElementalCreation.new(:video_source, change, parents: Array[:video])
+    }
+  }
+
+  # Override wanted-filenames method from StaticState with one that prevents our generated
+  # video segments from being deleted.
+  # This is still very hacky until I can guarantee/control the number of segments we get.
+  def wanted_files
+    dd_dest = File.join(the_setting_sun(:jekyll, :destination).to_s, @relative_dest)
+    changes.each_with_object(Set[]) { |change, wanted|
+      case change.type
+      # Treat HLS and MPEG-DASH the same, with slightly different naming conventions.
+      # Add their main playlist file, but then also glob any segments that happen to exist.
+      when CHECKING::YOU::OUT['application/dash+xml']
+        hls_dir = File.join(dd_dest, "#{basename}.hls")
+        wanted.add(File.join(hls_dir, "#{basename}.m3u8"))
+        if Dir.exist?(hls_dir)
+          Dir.entries(hls_dir).to_set.subtract(Set["#{basename}.m3u8"]).each { |hls| wanted.add(File.join(hls_dir, hls)) }
+        end
+      when CHECKING::YOU::OUT['application/vnd.apple.mpegurl']
+        dash_dir = File.join(dd_dest, "#{basename}.dash")
+        wanted.add(File.join(dash_dir, "#{basename}.mpd"))
+        if Dir.exist?(dash_dir)
+          Dir.entries(dash_dir).to_set.subtract(Set["#{basename}.mpd"]).each { |dash| wanted.add(File.join(dash_dir, dash)) }
+        end
+      else
+        # Treat any other type (including single-file video types) like normal.
+        wanted.add(change.name)
+      end
+    }
+  end
+
+end  # Video

data/lib/distorted-jekyll/monkey_business/jekyll/cleaner.rb

@@ -0,0 +1,121 @@
+require 'set'
+require 'distorted-jekyll/media_molecule'
+
+module Jekyll
+  # Handles the cleanup of a site's destination before it is built or re-built.
+  class Cleaner
+
+    # Private: The list of files to be created when site is built.
+    #
+    # Returns a Set with the file paths
+    #
+    # Monkey-patch this to look for DD's unique `destinations` which is similar
+    # to the original `destination` method except it returns a Set of destination
+    # paths instead of a single destination path.
+    # Do the patch with `define_method` instead of just `def` because the block's
+    # closure of the local scope lets it carry a binding to the original overriden
+    # method which I use to bail out iff the monkey-patch fails.
+    # This is an attempt to avoid breaking future Jekyll versions as much as
+    # possible, since any Exception in the monkey-patched code will just cause
+    # the original Jekyll implementation to be called instead.
+    # The new worst case scenario is slow site builds due to media variation generation!
+    #
+    # If a StaticFile responds to `destinations` then use it and merge the result.
+    # I'm defining my own separate method for multi-destinations for now,
+    # but I also considered just overriding `destination` to return the Set and
+    # then doing this as a one-liner that handles either case (single or
+    # multiple destinations) with `files.merge(Set[*(item.destination(site.dest))])`.
+    # This is the safer choice though since we avoid changing the outout type of the
+    # regular `:destination` method.
+    the_old_new_thing = instance_method(:new_files)
+    define_method(:new_files) do
+      begin
+        @new_files ||= Set.new.tap do |files|
+          site.each_site_file { |item|
+            if item.respond_to?(:destinations)
+              files.merge(item.destinations(site.dest))
+            elsif item.respond_to?(:destination)
+              files << item.destination(site.dest)
+            else
+              # Something unrelated has gone wrong for us to end up sending
+              # `destination` to something that doesn't respond to it.
+              # We should fall back to the original implementation of `new_files`
+              # in this case so the failure doesn't appear to be here.
+              the_old_new_thing.bind(self).()
+            end
+          }
+        end
+      rescue RuntimeError => e
+        Jekyll.logger.warn('DistorteD', "Monkey-patching Jekyll::Cleaner#new_files failed: #{e.message}")
+        Jekyll.logger.debug('DistorteD', "Monkey-patched Jekyll::Cleaner#new_files backtrace: #{e.backtrace}")
+        the_old_new_thing.bind(self).()
+      end
+    end  # define_method :new_files
+
+
+    # Private: Creates a regular expression from the config's keep_files array
+    #
+    # Examples
+    #   ['.git','.svn'] with site.dest "/myblog/_site" creates
+    #   the following regex: /\A\/myblog\/_site\/(\.git|\/.svn)/
+    #
+    # Returns the regular expression
+    #
+    # Monkey-patch this to protect DistorteD-generated files from destruction
+    # https://jekyllrb.com/docs/configuration/incremental-regeneration/
+    # when running Jekyll in Incremental mode twice in a row.
+    #
+    # The first Incremental build will process our Liquid tags on every post/page
+    # which will add our generated files to Jekyll::Cleaner's :new_files (See above!)
+    # A second build, however, will not re-process any posts/pages that haven't changed.
+    # Our Tags never get initialized, so their previously-generated files now appear
+    # to be spurious and will get purged.
+    #
+    # Work around this by merging Jekyll::Cleaner#keep_file_regex with a second Regexp
+    # based on the :preferred_extension for every MIME::Type DistorteD can output.
+    mr_regular = instance_method(:keep_file_regex)
+    define_method(:keep_file_regex) do
+      begin
+        # We're going to use it either way, so go ahead and get what the :keep_file_regex
+        # would have been in unpatched Jekyll, e.g.:
+        # (?-mix:\A/home/okeeblow/Works/cooltrainer/_site\/(\.git|\.svn))
+        super_regexp = mr_regular.bind(self).()
+
+        # If we aren't in Incremental mode then each Tag will explicitly declare
+        # the files they write, and that's preferrable to this shotgun approach
+        # since the Regexp approach may preserve unwanted files, but "Some unwanted files"
+        # is way nicer than "fifteen minutes rebuilding everything" rofl
+        if site&.incremental?
+          # Discover every supported output MIME::Type based on every loaded MediaMolecule.
+          outer_limits = Cooltrainer::DistorteD::IMPLANTATION(
+            :OUTER_LIMITS,
+            Cooltrainer::DistorteD::media_molecules,
+          ).values.flat_map(&:keys)
+
+          # Build a new Regexp globbing the preferred extension of every Type we support, e.g.:
+          # (?-mix:\A/home/okeeblow/Works/cooltrainer/_site/.*(txt|nfo|v|ppm|pgm|pbm|hdr|png|jpg|webp|tiff|fits|gif|bmp|ttf|svg|pdf|mpd|m3u8|mp4))
+          #
+          # Some Types may have duplicate preferred_extensions, and some might have nil
+          # (e.g. our own application/x.distorted.never-let-you-down), so :uniq and :compact them out.
+          outer_regexp = %r!\A#{Regexp.quote(site.dest)}/.*(#{Regexp.union(outer_limits&.map(&:preferred_extension).uniq.compact).source})!
+
+          # Do the thing.
+          combined_regexp = Regexp.union(outer_regexp, super_regexp)
+          Jekyll.logger.debug(
+            'Protecting DistorteD-generated files from Incremental-mode destruction with new Jekyll::Cleaner#keep_file_regex',
+            combined_regexp.source)
+          return combined_regexp
+        else
+          # Feels like I'm patching nothin' at all… nothin' at all… nothin' at all!
+          return super_regexp
+        end
+      rescue RuntimeError => e
+        Jekyll.logger.warn('DistorteD', "Monkey-patching Jekyll::Cleaner#keep_file_regex failed: #{e.message}")
+        Jekyll.logger.debug('DistorteD', "Monkey-patched Jekyll::Cleaner#keep_file_regex backtrace: #{e.backtrace}")
+        # Bail out by returning what the :keep_file_regex would have been without this patch.
+        mr_regular.bind(self).()
+      end
+    end  # define_method :keep_file_regex
+
+  end  # Cleaner
+end  # Jekyll

data/lib/distorted-jekyll/static_state.rb

@@ -0,0 +1,160 @@
+
+require 'fileutils'
+require 'set'
+
+require 'distorted/error_code'
+
+
+module Jekyll; end
+module Jekyll::DistorteD; end
+
+# This module implements the methods our tag needs in order to
+# pretend to be a Jekyll::StaticFile so we don't need to
+# redundantly re-implement a Generator and Jekyll::Cleaner.
+module Jekyll::DistorteD::StaticState
+
+
+  # Returns the to-be-written path of a single standard StaticFile.
+  # The value returned by this method is only the 'main' or 'original'
+  # (even if modified somehow) file and does not include the
+  # path/filenames of any variations.
+  # This method will be called by jekyll/lib/cleaner#new_files
+  # to generate the list of files that need to be build or rebuilt
+  # for a site. For this reason, this method shouldn't do any kind
+  # of checking the real filesystem, since e.g. its URL-based
+  # destdir might not exist yet if the Site.dest is completely blank.
+  def destination(dest_root)
+    File.join(dest_root, @relative_dest, @name)
+  end
+
+  # This method will be called by our monkey-patched Jekyll::Cleaner#new_files
+  # in place of the single-destination method usually used.
+  # This allows us to tell Jekyll about more than a single file
+  # that should be kept when regenerating the site.
+  # This makes DistorteD fast!
+  def destinations(dest_root)
+    changes&.flat_map { |change| change.paths(dest_root) }
+  end
+
+  # HACK HACK HACK
+  # Jekyll does not pass this method a site.dest like it does write() and
+  # others, but I want to be able to short-circuit here if all the
+  # to-be-generated files already exist.
+  def modified?
+    # Assume modified for the sake of freshness :)
+    modified = true
+
+    site_dest = the_setting_sun(:jekyll, :destination).to_s
+    if Dir.exist?(site_dest)
+      if Dir.exist?(File.join(site_dest, @relative_dest))
+        extant_files = Dir.entries(File.join(site_dest, @relative_dest)).to_set
+
+        # TODO: Make this smarter. It's not enough that all the generated
+        # filenames should exist. Try a few more ways to detect subtler
+        # "changes to the source file since generation of variations.
+        if wanted_files.subset?(extant_files)
+          Jekyll.logger.debug(@name, "All variations present: #{wanted_files}")
+          modified = false
+        else
+          Jekyll.logger.debug(@name, "Missing variations: #{wanted_files - extant_files}")
+        end
+
+      end  # relative_dest.exists?
+    end  # site_dest.exists?
+    Jekyll.logger.debug("#{@name} modified?",  modified)
+    return modified
+  end  # modified?
+
+  # Whether to write the file to the filesystem
+  #
+  # Returns true unless the defaults for the destination path from
+  # _config.yml contain `published: false`.
+  def write?
+    publishable = defaults.fetch('published'.freeze, true)
+    return publishable unless @collection
+
+    publishable && @collection.write?
+  end
+
+  # Write the static file to the destination directory (if modified).
+  #
+  # dest - The String path to the destination dir.
+  #
+  # Returns false if the file was not modified since last time (no-op).
+  def write(dest_root)
+    return false if File.exist?(path) && !modified?
+
+    # Create any directories to the depth of the intended destination.
+    FileUtils.mkdir_p(File.join(dest_root, @relative_dest))
+    # Save every desired variation of this image.
+    # This will be a Set of Hashes each describing the name, type,
+    # dimensions, attributes, etc of each output variation we want.
+    # Full-size outputs will have the special tag `:full`.
+    changes&.each { |change|
+      if self.respond_to?(change.type.distorted_file_method)
+        Jekyll.logger.debug("DistorteD::#{change.type.distorted_file_method}", change.name)
+        # 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/
+        self.send(change.type.distorted_file_method, dest_root, change, **{})
+      elsif extname == ".#{change.type.preferred_extension}"
+        Jekyll.logger.debug(@name, <<~RAWCOPY
+            No #{change.type.distorted_file_method} method is defined,
+            but the intended output type #{change.type.to_s} is the same
+            as the input type, so I will fall back to copying the raw file.
+          RAWCOPY
+        )
+        copy_file(change.paths(dest_root).first)
+      else
+        Jekyll.logger.error(@name, "Missing write method #{change.type.distorted_file_method}")
+        raise MediaTypeOutputNotImplementedError.new(change.path(dest_root), type_mars, self.class.name)
+      end
+    }
+  end  # write
+
+  private
+
+  def copy_file(dest_path, *a, **k)
+    if @site.safe || Jekyll.env == "production"
+      FileUtils.cp(path, dest_path)
+    else
+      FileUtils.copy_entry(path, dest_path)
+    end
+  end  # copy_file
+
+  # Basic file properties
+
+  # Returns the extname /!\ including the dot /!\
+  def extname
+    File.extname(@name)
+  end
+
+  # Returns last modification time for this file.
+  def mtime
+    (@modified_time ||= File.stat(path).mtime).to_i
+  end
+
+  # Returns source file path.
+  def path
+    @path ||= begin
+      # Static file is from a collection inside custom collections directory
+      if !@collection.nil? && !@site.config['collections_dir'.freeze].empty?
+        File.join(*[@base, @site.config['collections_dir'.freeze], @dir, @name].compact)
+      else
+        File.join(*[@base, @dir, @name].compact)
+      end
+    end
+  end
+
+
+  # Returns a Set of just the String filenames we want for this media.
+  # This will be used by `modified?` among others.
+  def wanted_files
+    # Cooltrainer::Change#names returns an Array[String], so we must concat every Change into one.
+    changes.map(&:names).reduce(&:concat).to_set
+  end
+
+
+end