jekyll_picture_tag 1.2.0

data/lib/jekyll_picture_tag/output_formats/data_img.rb

@@ -0,0 +1,8 @@
+module PictureTag
+  module OutputFormats
+    # img with data-src and such instead of src
+    class DataImg < Img
+      include DataAttributes
+    end
+  end
+end

data/lib/jekyll_picture_tag/output_formats/data_picture.rb

@@ -0,0 +1,8 @@
+module PictureTag
+  module OutputFormats
+    # picture tag with data-srcsets and such instead of src.
+    class DataPicture < Picture
+      include DataAttributes
+    end
+  end
+end

data/lib/jekyll_picture_tag/output_formats/direct_url.rb

@@ -0,0 +1,13 @@
+module PictureTag
+  module OutputFormats
+    # Represents a bare url you can use in another context, such as a direct
+    # link, but keep the resizing functionality
+    class DirectUrl
+      include PictureTag::OutputFormats::Basics
+
+      def to_s
+        build_base_img.src
+      end
+    end
+  end
+end

data/lib/jekyll_picture_tag/output_formats/img.rb

@@ -0,0 +1,24 @@
+module PictureTag
+  module OutputFormats
+    # Represents a bare <img> tag with a srcset attribute.
+    # Used when <picture> is unnecessary.
+    class Img
+      include PictureTag::OutputFormats::Basics
+
+      def srcset
+        build_srcset(nil, PictureTag.preset['formats'].first)
+      end
+
+      def base_markup
+        img = build_base_img
+
+        add_srcset(img, srcset)
+        add_sizes(img, srcset)
+
+        img.attributes << PictureTag.html_attributes['parent']
+
+        img
+      end
+    end
+  end
+end

data/lib/jekyll_picture_tag/output_formats/picture.rb

@@ -0,0 +1,66 @@
+module PictureTag
+  module OutputFormats
+    # Represents a <picture> tag, enclosing at least 2 <source> tags and an
+    # <img> tag.
+    class Picture
+      include Basics
+
+      def srcsets
+        sets = []
+
+        PictureTag.preset['formats'].each do |format|
+          # We have 2 dimensions here: formats, and source images. Formats are
+          # provided in the order they must be returned, source images are
+          # provided in the reverse (least to most preferable) and must be
+          # flipped. We'll use an intermediate value to accomplish this.
+          format_set = []
+
+          # Source images are defined in the tag params, and associated with
+          # media queries. The base (first provided) image has a key of nil.
+          PictureTag.source_images.each_key do |media|
+            format_set << build_srcset(media, format)
+          end
+          sets.concat format_set.reverse
+        end
+
+        sets
+      end
+
+      def build_sources
+        srcsets.collect { |s| build_source(s) }
+      end
+
+      def build_source(srcset)
+        source = SingleTag.new(
+          'source',
+          attributes: PictureTag.html_attributes['source']
+        )
+
+        # Sizes will be the same for all sources. There's some redundant markup
+        # here, but I don't think it's worth the effort to prevent.
+        add_sizes(source, srcset)
+        add_media(source, srcset)
+        add_srcset(source, srcset)
+
+        source.type = srcset.mime_type
+
+        source
+      end
+
+      def base_markup
+        picture = DoubleTag.new(
+          'picture',
+          attributes: PictureTag.html_attributes['picture'],
+          content: build_sources << build_base_img,
+
+          # Markdown fix requires removal of line breaks:
+          oneline: PictureTag.nomarkdown?
+        )
+
+        picture.attributes << PictureTag.html_attributes['parent']
+
+        picture
+      end
+    end
+  end
+end

data/lib/jekyll_picture_tag/source_image.rb

@@ -0,0 +1,62 @@
+module PictureTag
+  # Handles a given source image file and its properties. Provides a speed
+  # advantage by storing expensive file reads and writes in instance variables,
+  # to be reused by many different source images.
+  class SourceImage
+    attr_reader :name, :shortname
+
+    def initialize(relative_filename)
+      @shortname = relative_filename
+      @name = grab_file relative_filename
+    end
+
+    def size
+      @size ||= build_size
+    end
+
+    def width
+      size[:width]
+    end
+
+    def aspect_ratio
+      @aspect_ratio ||= size[:width].to_f / size[:height].to_f
+    end
+
+    def digest
+      @digest ||= Digest::MD5.hexdigest(File.read(@name))[0..5]
+    end
+
+    # Includes path relative to default sorce folder, and the original filename.
+    def base_name
+      @shortname.delete_suffix File.extname(@shortname)
+    end
+
+    # File exention
+    def ext
+      # [1..-1] will strip the leading period.
+      @ext ||= File.extname(@name)[1..-1].downcase
+    end
+
+    private
+
+    def build_size
+      width, height = FastImage.size(@name)
+
+      {
+        width: width,
+        height: height
+      }
+    end
+
+    # Turn a relative filename into an absolute one, and make sure it exists.
+    def grab_file(source_file)
+      source_name = File.join(PictureTag.config.source_dir, source_file)
+
+      unless File.exist? source_name
+        raise "Jekyll Picture Tag could not find #{source_name}."
+      end
+
+      source_name
+    end
+  end
+end

data/lib/jekyll_picture_tag/srcsets.rb

@@ -0,0 +1,3 @@
+require_relative 'srcsets/basics'
+require_relative 'srcsets/pixel_ratio'
+require_relative 'srcsets/width'

data/lib/jekyll_picture_tag/srcsets/basics.rb

@@ -0,0 +1,88 @@
+module PictureTag
+  # Handles srcset generation, which also handles file generation.
+  module Srcsets
+    # Basic functionality for a srcset, which also handles file generation.
+    # Classes including this module must implement the to_a method, which
+    # accomplishes the following:
+    # - Return an array of srcset entries.
+    # - Call generate_file for each entry, giving it the desired width in
+    #   pixels.
+    module Basics
+      require 'fastimage'
+      attr_reader :media, :source_image
+
+      def initialize(media:, format:)
+        @media = media # Associated Media Query, can be nil
+
+        # Output format:
+        @format = Utils.process_format(format, media)
+
+        @source_image = PictureTag.source_images[@media]
+      end
+
+      def to_s
+        to_a.join(', ')
+      end
+
+      # Allows us to add a type attribute to whichever element contains this
+      # srcset.
+      def mime_type
+        mime_types[@format]
+      end
+
+      # Some srcsets have them, for those that don't return nil.
+      def sizes
+        nil
+      end
+
+      # Check our source image size vs requested sizes
+      def check_widths(targets)
+        if targets.any? { |t| t > @source_image.width }
+          handle_small_source(targets, @source_image.width)
+        else
+          targets
+        end
+      end
+
+      # Generates an HTML attribute
+      def media_attribute
+        "(#{PictureTag.media_presets[@media]})"
+      end
+
+      private
+
+      def handle_small_source(targets, image_width)
+        PictureTag::Utils.warning(
+          " #{@source_image.shortname} is #{image_width}px wide, smaller than" \
+          " at least one size in the set #{targets}. Will not enlarge."
+        )
+
+        small_targets = targets.dup.delete_if { |t| t >= image_width }
+
+        small_targets.push image_width
+
+        small_targets
+      end
+
+      def generate_file(width)
+        GeneratedImage.new(
+          source_file: @source_image,
+          width: width,
+          format: @format
+        )
+      end
+
+      # Hardcoding these isn't ideal, but I'm not pulling in a new dependency
+      # for 9 lines of easy code.
+      def mime_types
+        {
+          'gif'  => 'image/gif',
+          'jpg'  => 'image/jpeg',
+          'jpeg' => 'image/jpeg',
+          'png'  => 'image/png',
+          'webp' => 'image/webp'
+        }
+      end
+    end
+  end
+end

data/lib/jekyll_picture_tag/srcsets/pixel_ratio.rb

@@ -0,0 +1,32 @@
+module PictureTag
+  module Srcsets
+    # Creates a srcset in the "(filename) (pixel_ratio)x" format.
+    # Example: "img.jpg 1x, img2.jpg 1.5x, img3.jpg 2x"
+    class PixelRatio
+      include Basics
+
+      def to_a
+        widths.collect { |w| build_srcset_entry(w) }
+      end
+
+      private
+
+      def widths
+        target = PictureTag.preset['pixel_ratios'].collect do |p|
+          p * PictureTag.preset['base_width']
+        end
+
+        check_widths target
+      end
+
+      def build_srcset_entry(width)
+        # We have to recalculate the pixel ratio after verifying our source
+        # image is large enough.
+        pixel_ratio = (width.to_f / PictureTag.preset['base_width']).round(2)
+        file = generate_file(width)
+
+        "#{PictureTag.build_url(file.name)} #{pixel_ratio}x"
+      end
+    end
+  end
+end

data/lib/jekyll_picture_tag/srcsets/width.rb

@@ -0,0 +1,45 @@
+module PictureTag
+  module Srcsets
+    # Creates a srcset in the "(filename) (width)w, (...)" format.
+    # Example: "img.jpg 400w, img2.jpg 600w, img3.jpg 800w"
+    class Width
+      include Basics
+
+      def to_a
+        widths.collect { |w| build_srcset_entry(w) }
+      end
+
+      # Sizes html attribute. Since it's intimately related to srcset, we
+      # generate it at the same time.
+      def sizes
+        preset_sizes = PictureTag.preset['sizes'] || {}
+        preset_size = PictureTag.preset['size']
+        size_set = []
+
+        preset_sizes.each_pair do |media, size|
+          size_set << build_size_entry(media, size)
+        end
+
+        size_set << preset_size if preset_size
+
+        size_set.any? ? size_set.join(', ') : nil
+      end
+
+      private
+
+      def widths
+        check_widths PictureTag.widths(@media)
+      end
+
+      def build_srcset_entry(width)
+        file = generate_file(width)
+
+        "#{PictureTag.build_url(file.name)} #{file.width}w"
+      end
+
+      def build_size_entry(media, size)
+        "(#{PictureTag.media_presets[media]}) #{size}"
+      end
+    end
+  end
+end

data/lib/jekyll_picture_tag/utils.rb

@@ -0,0 +1,67 @@
+module PictureTag
+  # This is a little module to hold logic that doesn't fit other places. If it
+  # starts getting big, refactor.
+  module Utils
+    # Configure Jekyll to keep our generated files
+    def self.keep_files
+      dest_dir = PictureTag.config['picture']['output']
+
+      # Chop a slash off the end, if it's there. Doesn't work otherwise.
+      dest_dir = dest_dir[0..-2] if dest_dir =~ %r{/\z}
+
+      return if PictureTag.site.config['keep_files'].include?(dest_dir)
+
+      PictureTag.site.config['keep_files'] << dest_dir
+    end
+
+    # Print a warning to the console
+    def self.warning(message)
+      return if PictureTag.config['picture']['suppress_warnings']
+
+      warn 'Jekyll Picture Tag Warning: '.yellow + message
+    end
+
+    # Parse a liquid template; allows liquid variables to be included as tag
+    # params.
+    def self.liquid_lookup(params)
+      Liquid::Template.parse(params).render(PictureTag.context)
+
+      # This gsub allows people to include template code for javascript
+      # libraries such as handlebar.js. It adds complication and I'm not sure
+      # it has much value now, so I'm commenting it out. If someone has a use
+      # case for it we can add it back in.
+      # .gsub(/\\\{\\\{|\\\{\\%/, '\{\{' => '{{', '\{\%' => '{%')
+    end
+
+    # Allows us to use 'original' as a format name.
+    def self.process_format(format, media)
+      if format.casecmp('original').zero?
+        PictureTag.source_images[media].ext
+      else
+        format.downcase
+      end
+    end
+
+    # Used for auto markup configuration and such
+    def self.count_srcsets
+      formats = PictureTag.preset['formats'].length
+      source_images = PictureTag.source_images.length
+
+      formats * source_images
+    end
+
+    # Returns whether or not the current page is a markdown file.
+    def self.markdown_page?
+      page_name = PictureTag.page['name']
+      page_ext = PictureTag.page['ext']
+      ext = page_ext ? page_ext : File.extname(page_name)
+
+      ext.casecmp('.md').zero? || ext.casecmp('.markdown').zero?
+    end
+
+    # Returns the widest source image
+    def self.biggest_source
+      PictureTag.source_images.values.max_by(&:width)
+    end
+  end
+end

data/lib/jekyll_picture_tag/version.rb

@@ -0,0 +1,3 @@
+module PictureTag
+  VERSION = '1.2.0'.freeze
+end

data/migration.md

@@ -0,0 +1,178 @@
+# Update and Migration guide
+
+This document details the changes from previous versions (Everything before 1.0), and how to migrate
+an existing site to the new version. For now it's a markdown document, once this branch is merged
+into master it'll be a wiki page.
+
+## Changes from previous versions:
+
+-   The default output formats are bone-stock HTML. Picturefill, as of version 3, no longer requires
+    special markup, so it remains compatible. Other javascript image solutions are supported with
+    the `data_` selection of markup formats. Interchange support is removed, though adding it again
+    is not difficult if there is demand for it.
+-   There are now 2 basic markup formats to choose from: `<source>` tags within a `<picture>`, and a
+    single `<img>` tag. If markup is set to 'auto', or if it is not set at all, the plugin will
+    automatically determine which is most appropriate. These formats also have `data_` counterparts
+    (i.e.  `data_auto`), which accomplish the same thing except setting respective data-attributes
+    to allow for lazy loading and such.
+-   There are also 2 srcset formats: one which supplies image width, and another which supplies
+    multiples (pixel ratios) of the base size.
+-   Source Keys are replaced by media query presets, which can also be used to create the 'sizes'
+    attribute.
+-   Jekyll Picture Tag no longer accepts height arguments, and will no longer crop images for you.
+    Aspect ratio will always be maintained.
+-   Multiple image widths are now supported, which will be used to create a corresponding srcset.
+-   Multiple image formats are now possible, including webp.
+-   PictureTag can now generate sizes attributes.
+-   Configuration takes a very different format. It should be simpler to write your config than the
+    old version, and migrating to it should not be difficult. Instead of creating individual source
+    keys, you supply an array of widths you'd like to construct. You can also supply an array (yaml
+    sequence) of formats, including 'original'.
+-   Only global settings are placed in `_config.yml`. Presets are moved to `_data/picture.yml`.
+
+## Migration
+
+### Liquid Tags
+
+Previous tag syntax has been extended, but backwards compatibility (and behaviour of previous
+versions) is maintained. 
+
+`{% picture img.jpg (implicit attributes) --(argument) (explicit attributes) %}`
+
+Implicit attributes are the old way. They are specified after the last source image, and before any
+explicit attributes (if they are included). These attributes are applied to the `<img>` tag, as in
+previous versions.
+
+Explicit attributes are the new way, documented in the readme. It is possible to use a mix of both,
+though I'm not sure why you would want to.
+
+There is one instance I can think of where you will have to change your tags:
+
+-   You use art direction with more than one different preset.
+-   These presets have source keys of the same name.
+-   These source keys have different associated media queries.
+
+If all of the above are true, you will either have to pick one media query which works for both, or
+rename one of them and change it everywhere it's used.
+
+Another trouble spot will be CSS; your output markup may change, meaning your CSS selectors may stop
+working.
+
+Outside of those situations, and provided you have created media_presets to match your old source
+keys, your existing tags should keep working. If they don't, it's a bug. Please report it.
+
+### Configuration
+
+The new configuration is described in the readme so I won't document it here, but I will show an old
+config alongside an equivalent new one.
+
+Example old configuration:
+
+```yml
+# _config.yml
+
+picture:
+  source: assets/images/_fullsize
+  output: generated
+  markup: picture
+  presets:
+    # Full width pictures
+    default:
+      ppi: [1, 1.5]
+      attr:
+        class: blog-full
+        itemprop: image
+      source_lrg:
+        media: "(min-width: 40em)"
+        width: 700
+      source_med:
+        media: "(min-width: 30em)"
+        width: 450
+      source_default:
+        width: 350
+        height: 200
+    # Half width pictures
+    half:
+      ppi: [1, 1.5]
+      attr:
+        data-location: "{{location}}"
+        data-active: nil
+      source_lrg:
+        media: "(min-width: 40em)"
+        width: 400
+      source_med:
+        media: "(min-width: 30em)"
+        width: 250
+      source_default:
+        width: 350
+    # Self-set resolution sources. Useful if you don't want a 1:1 image size to dppx ratio.
+    gallery:
+      source_wide_hi:
+        media: "(min-width: 40em) and (min-resolution: 1.5dppx)"
+        width: 900
+        height: 600
+      source_wide:
+        media: "(min-width: 40em)"
+        width: 600
+        height: 400
+      source_default:
+        width: 250
+        height: 250
+```
+
+Equivalent new configuration:
+
+```yml
+# _config.yml
+
+picture:
+  source: assets/images/_fullsize
+  output: generated
+```
+
+```yml
+# _data/picture.yml
+
+# Media presets are named media queries. To maintain compatibility with your tags, you need to
+# create presets of the same name as your old source keys. There is no limit to how many of them you
+# can have, so you're free to create additional new ones with better names to use going forward.
+media_presets:
+  source_lrg: '(min-width: 40em)'
+  source_med: '(min-width: 30em)'
+  source_wide_hi: "(min-width: 40em) and (min-resolution: 1.5dppx)"
+  source_wide: "(min-width: 40em)"
+
+markup_presets:
+  # You can't specify both widths and pixel ratios anymore. Choose one.
+  # Full width pictures, width-based srcset
+  default:
+    markup: picture
+    widths: [350, 450, 700]
+    attributes:
+      picture: 'class="blog-full" itemprop="image"'
+      
+  # Full width pictures, multiplier based srcset
+  default-ppi:
+    markup: picture
+    base_width: 350
+    pixel_ratios: [1, 1.5]
+    attributes:
+      picture: 'class="blog-full" itemprop="image"'
+
+  # Half width pictures
+  half:
+    widths: [250, 350, 400]
+    attributes: 
+      picture: 'data-location="{{location}}" data-active="nil"'
+
+  # Note you can't set heights anymore. You'll have to crop your images either ahead of time, or
+  # do it with CSS.
+  # 
+  # You have to use arrays for widths, even if only specifying a single value. There's no reason you
+  # can't add more.
+  gallery:
+    widths: [250]
+    media_widths:
+      source_wide_hi: [900]
+      source_wide: [600]
+```