jekyll_picture_tag 1.9.0 → 1.12.0

data/docs/users/presets/link_source.md

@@ -0,0 +1,16 @@
+---
+sort: 10
+---
+
+# Source Image Link
+
+_Format:_ `link_source: (true|false)`
+
+_Example:_ `link_source: true`
+
+_Default:_ `false`
+
+Surround image with a link to the original source file. Your source image
+directory must be published as part of the compiled site. If you run into weird
+issues with the output, see the [notes]({{ site.baseurl }}/notes).
+

data/docs/users/presets/markup_formats/fragments.md

@@ -0,0 +1,48 @@
+---
+sort: 3
+---
+
+# Fragments
+
+The following are not complete markup; they're building blocks that you can use
+to make things outside the scope of JPT.
+
+- `direct_url` Generates an image and returns only its url. Uses
+  `fallback_width` and `fallback_format`.
+
+  ```yml
+  # _data/picture.yml
+
+  markup_presets:
+    direct:
+      markup: direct_url
+      fallback_width: 800
+      fallback_format: webp
+  ```
+
+  ```
+  {% raw %}
+  {% picture direct myimage.jpg %} --> /generated/myimage-800-abcd12345.webp
+  {% endraw %}
+  ```
+
+- `naked_srcset`: Builds a srcset and nothing else (not even the surrounding quotes). Note that the
+  (image) `format` setting must still be an array, even if you only give it one
+  value. (This is on the list of things to improve.)
+
+  ```yml
+  # _data/picture.yml
+
+  markup_presets:
+    only_srcset:
+      markup: naked_srcset
+      widths: [800, 1200, 1600]
+      format: [webp]
+  ```
+
+  ```
+  {% raw %}
+  {% picture only_srcset myimage.jpg %} --> 
+  /generated/myimage-800-abcd12345.webp 800w, /generated/myimage-1200-abcd12345.webp 1200w, (...)
+  {% endraw %}
+  ```

data/docs/users/presets/markup_formats/javascript_friendly.md

@@ -0,0 +1,57 @@
+---
+sort: 2
+---
+
+# Javascript Friendly
+
+These are analogous to their plain HTML counterparts, but instead of `src`,
+`srcset`, and `sizes`, you get `data-src`, `data-srcset`, and `data-sizes`. This
+allows you to use javascript for things like [lazy
+loading](https://github.com/verlok/lazyload).
+
+- `data_picture`
+
+  ```html
+    <picture> 
+      <source data-srcset="..." data-sizes="...">
+      <source data-srcset="..." data-sizes="...">
+      (...)
+      <img data-src="...">
+    </picture>
+  ```
+
+- `data_img`
+  ```html
+    <img data-srcset="..." data-src="..." data-sizes="...">
+  ```
+
+- `data_auto` - `data_picture` when needed, otherwise `data_img`.
+
+## Special Options
+
+The following preset settings only apply to these output formats.
+
+- `noscript`
+
+  _Format:_ `noscript: true|false`
+
+  _Default:_ `false`
+
+  Include a basic `img` fallback within a `<noscript>` tag, giving your
+  non-javascript-running users something to look at.
+
+  ```html
+    <img data-srcset="..." data-src="..." data-sizes="...">
+    <noscript>
+      <img src="..." alt="...">
+    </noscript>
+  ```
+
+- `data_sizes`
+
+  _Format:_ `data_sizes: true|false`
+
+  _Default:_ `true`
+
+  This option sets whether you would like JPT's auto-generated sizes to be returned as a
+  `data-sizes` attribute or a normal `sizes` attribute.

data/docs/users/presets/markup_formats/readme.md

@@ -0,0 +1,43 @@
+---
+sort: 1
+---
+
+# Markup Formats
+
+Define what format the generated text will take. Select one by setting
+`markup:` in the relevant [preset]({{ site.baseurl }}/users/presets).
+
+_Format:_ `markup: (setting)`
+
+_Default_: `auto`
+
+
+Example:
+
+```yml
+# /_data/picture.yml
+
+markup_presets:
+  my_preset:
+    markup: data_auto
+```
+
+## Valid options:
+
+### Standard HTML:
+- `auto` - default
+- `picture`
+- `img`
+
+### Javascript Friendly:
+- `data_auto`
+- `data_picture`
+- `data_img`
+
+### Fragments:
+- `direct_url`
+- `naked_srcset`
+
+## Reference:
+
+{% include list.liquid %}

data/docs/users/presets/markup_formats/standard_html.md

@@ -0,0 +1,25 @@
+---
+sort: 1
+---
+
+# Standard HTML
+
+- **`picture`** - `<picture>` element surrounding a `<source>` tag for each required srcset, and a
+  fallback `<img>`:
+
+  ```html
+    <picture> 
+      <source srcset="..." sizes="..." media="..." type="...">
+      <source srcset="..." sizes="..." media="..." type="...">
+      (...)
+      <img src="...">
+    </picture
+  ```
+
+- **`img`** - a single `<img>` tag with a `srcset` entry:
+
+  ```html
+  <img src="..." srcset="..." sizes="..." alt="..." width="..." height="...">
+  ```
+
+- **`auto`** - Supply an img tag when you have only one srcset, otherwise supply a picture tag.

data/docs/users/presets/media_queries.md

@@ -0,0 +1,36 @@
+---
+sort: 1
+---
+
+# Media Queries
+
+Jekyll Picture Tag handles media queries by letting you define them by name in
+`_data/picture.yml`, and then referencing that name whenever you need it.
+
+_Format:_
+
+```yaml
+# _data/picture.yml
+
+media_queries:
+  (name): (css media query)
+  (name): (css media query)
+  (...)
+
+```
+
+_Example:_
+
+```yaml
+# _data/picture.yml
+
+media_queries:
+  mobile: "max-width: 600px"
+  tablet: "max-width: 800px"
+  ultrawide: "min-width: 1400px"
+```
+
+They are used in a few different places: specifying alternate source images in
+your liquid tag, building the 'sizes' attribute within your presets, and in a
+few configuration settings. Quotes are recommended, because yml gets confused by
+colons.

data/docs/users/presets/nomarkdown_override.md

@@ -0,0 +1,17 @@
+---
+sort: 11
+---
+
+# Nomarkdown Override
+
+_Format:_ `nomarkdown: (true|false)`
+
+_Example:_ `nomarkdown: false`
+
+_Default:_ `nil`
+
+Hard setting for `{::nomarkdown}` tags, overrides both autodetection and the
+global setting in `_config.yml`.
+
+See this [note]({{ site.baseurl }}/users/notes/kramdown_bug) for a detailed
+explanation.

data/docs/users/presets/pixel_ratio_srcsets.md

@@ -0,0 +1,32 @@
+---
+sort: 4
+---
+
+# Pixel Ratio Srcsets
+
+A Pixel Ratio srcset looks like this:
+
+```html
+srcset="myimage-200.jpg 1.0x, myimage-300.jpg 1.5x, myimage-400.jpg 2.0x" 
+```
+
+To use one, set `pixel_ratios` and `base_width`. They are most appropriate for
+thumbnails and icons, where the image will be the same size on all screens, and
+all you need to account for is pixel ratio.
+
+## Base Width
+
+_Format:_ `base_width: integer`
+
+_Example:_ `base_width: 100`
+
+Sets how wide the 1x image should be. Required when using a Pixel Ratio srcset.
+
+## Pixel Ratios
+
+_Format:_ `pixel_ratios: [number, number, number (...)]`
+
+_Example:_ `pixel_ratios: [1, 1.5, 2]`
+
+Array of images to construct, given in multiples of the base width.
+

data/docs/users/presets/width_height_attributes.md

@@ -0,0 +1,34 @@
+---
+sort: 7
+---
+
+# Width & Height (Anti-Loading-Jank)
+
+_Format:_
+
+```yml
+dimension_attributes: true | false
+```
+
+_Example:_
+
+```yml
+dimension_attributes: true
+```
+
+_Default:_ `false`
+
+Prevent page reflow (aka jank) while images are loading, by adding `width` and
+`height` attributes to the `<img>` tag in the correct aspect ratio.
+
+For an explanation of why and how you want to do this,
+[here](https://youtu.be/4-d_SoCHeWE) is a great explanation.
+
+Caveats: 
+  * You need either `width: auto;` or `height: auto;` set in CSS on the `<img>`
+  tags, or they will be stretched.
+  * This works on `<img>` tags and `<picture>` tags when offering images in
+  multiple widths and formats, but it does not work if you are using art
+  direction (in other words, if you have multiple source images). This is
+  because these attributes can only be applied to the `<img>` tag, of which
+  there is exactly one.

data/docs/users/presets/width_srcsets.md

@@ -0,0 +1,85 @@
+---
+sort: 3
+---
+
+# Width Based Srcsets
+
+A width based srcset looks like this: 
+
+```html
+srcset="myimage-800.jpg 800w, myimage-1200.jpg 1200w, myimage-2000.jpg 2000w"
+```
+
+It's the default; to use it specify a `widths` setting (or don't, for the
+default set), and optionally the `sizes` and `size` settings.
+
+## Widths
+
+_Format:_ `widths: [integer, integer, (...)]`
+
+_Example:_ `widths: [600, 800, 1200]`
+
+_Default_: `[400, 600, 800, 1000]`
+
+Array of image widths to generate, in pixels.
+
+## Media Widths
+
+_Format:_
+
+```yml
+media_widths:
+  (media_query name): [integer, integer, (...)]
+```
+
+_Example:_
+
+```yml
+media_widths:
+  mobile: [400, 600, 800]
+```
+
+_Default:_ `widths` setting
+
+If you are using art direction, there is no sense in generating desktop-size
+files for your mobile image. You can specify sets of widths to associate with
+given media queries. If not specified, will use `widths` setting.
+
+## Sizes
+
+_Format:_
+
+```yml
+sizes:
+  (media preset): (CSS dimension)
+  (...)
+```
+
+_Example:_
+
+```yml
+sizes:
+  mobile: 80vw
+  tablet: 60vw
+  desktop: 900px
+```
+
+Conditional sizes, used to construct the `sizes=` HTML attribute telling the
+browser how wide your image will be (on the screen) when a given media query
+is true. CSS dimensions can be given in `px`, `em`, or `vw`. To be used along
+with a width-based srcset.
+
+Provide these in order of most restrictive to least restrictive. The browser
+will choose the first one with an applicable media query.
+
+You don't have to provide a sizes attribute at all. If you don't, the browser
+will assume the image is 100% the width of the viewport.
+
+## Size
+
+_Format:_ `size: (CSS Dimension)`
+
+_Example:_ `size: 80vw`
+
+Unconditional `sizes` setting, to be supplied either alone or after all
+conditional sizes.

data/jekyll_picture_tag.gemspec

@@ -40,7 +40,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'addressable', '~> 2.6'
   spec.add_dependency 'mime-types', '~> 3'
   spec.add_dependency 'mini_magick', '~> 4'
-  spec.add_dependency 'objective_elements', '~> 1.1.1'
+  spec.add_dependency 'objective_elements', '~> 1.1.2'
 
   spec.add_runtime_dependency 'jekyll', '< 5'
 end

data/lib/jekyll_picture_tag.rb

@@ -9,6 +9,7 @@ require_relative 'jekyll_picture_tag/srcsets'
 require_relative 'jekyll_picture_tag/utils'
 require_relative 'jekyll_picture_tag/img_uri'
 require_relative 'jekyll_picture_tag/router'
+require_relative 'jekyll_picture_tag/cache'
 
 # Title: Jekyll Picture Tag
 # Authors: Rob Wierzbowski   : @robwierzbowski

data/lib/jekyll_picture_tag/cache.rb

@@ -0,0 +1,3 @@
+require_relative 'cache/base'
+require_relative 'cache/source'
+require_relative 'cache/generated'

data/lib/jekyll_picture_tag/cache/base.rb

@@ -0,0 +1,59 @@
+require 'json'
+
+module PictureTag
+  module Cache
+    # Basic image information cache functionality
+    module Base
+      def initialize(base_name)
+        @base_name = base_name
+      end
+
+      def [](key)
+        data[key]
+      end
+
+      def []=(key, value)
+        raise ArgumentError unless template.keys.include? key
+
+        data[key] = value
+      end
+
+      # Call after updating data.
+      def write
+        FileUtils.mkdir_p(File.join(base_directory, sub_directory))
+
+        File.open(filename, 'w+') do |f|
+          f.write JSON.generate(data)
+        end
+      end
+
+      private
+
+      def data
+        @data ||= if File.exist?(filename)
+                    JSON.parse(File.read(filename)).transform_keys(&:to_sym)
+                  else
+                    template
+                  end
+      end
+
+      # /home/dave/my_blog/.jekyll-cache/jpt/(cache_dir)/assets/myimage.jpg.json
+      # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      def base_directory
+        File.join(PictureTag.site.cache_dir, 'jpt', cache_dir)
+      end
+
+      # /home/dave/my_blog/.jekyll-cache/jpt/(cache_dir)/assets/myimage.jpg.json
+      #                                                 ^^^^^^^^
+      def sub_directory
+        File.dirname(@base_name)
+      end
+
+      # /home/dave/my_blog/.jekyll-cache/jpt/somefolder/myimage.jpg.json
+      # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      def filename
+        File.join(base_directory, @base_name + '.json')
+      end
+    end
+  end
+end