jekyll_picture_tag 1.11.0 → 1.12.0

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/lib/jekyll_picture_tag/instructions/preset.rb

@@ -81,9 +81,13 @@ module PictureTag
       end
 
       def grab_data_file
+        search_data('presets') || search_data('markup_presets') || no_preset
+      end
+
+      def search_data(key)
         PictureTag.site
                   .data
-                  .dig('picture', 'markup_presets', @name) || no_preset
+                  .dig('picture', key, @name)
       end
 
       def no_preset

data/lib/jekyll_picture_tag/instructions/set.rb

@@ -27,7 +27,7 @@ module PictureTag
       # These are our Media Query presets. It's really just a hash, and there
       # are no default values, so extracting this to its own class is overkill.
       def media_presets
-        PictureTag.site.data.dig('picture', 'media_presets') || {}
+        search_data('media_queries') || search_data('media_presets') || {}
       end
 
       def source_images
@@ -52,6 +52,10 @@ module PictureTag
 
       private
 
+      def search_data(key)
+        PictureTag.site.data.dig('picture', key)
+      end
+
       def build_source_images
         source_names = params.source_names
         media_presets = params.media_presets

data/lib/jekyll_picture_tag/version.rb

@@ -1,3 +1,3 @@
 module PictureTag
-  VERSION = '1.11.0'.freeze
+  VERSION = '1.12.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_picture_tag
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.12.0
 platform: ruby
 authors:
 - Robert Wierzbowski
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-27 00:00:00.000000000 Z
+date: 2020-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -232,19 +232,60 @@ files:
 - docs/Gemfile
 - docs/Gemfile.lock
 - docs/_config.yml
-- docs/_layouts/directory.html
-- docs/assets/style.css
-- docs/contributing.md
-- docs/example_presets.md
-- docs/global_configuration.md
+- docs/devs/contributing/code.md
+- docs/devs/contributing/docs.md
+- docs/devs/contributing/index.md
+- docs/devs/contributing/setup.md
+- docs/devs/contributing/testing.md
+- docs/devs/index.md
+- docs/devs/releases.md
 - docs/index.md
-- docs/installation.md
-- docs/migration.md
-- docs/notes.md
-- docs/output.md
-- docs/presets.md
-- docs/releases.md
-- docs/usage.md
+- docs/users/configuration/cdn.md
+- docs/users/configuration/directories.md
+- docs/users/configuration/disable.md
+- docs/users/configuration/fast_build.md
+- docs/users/configuration/ignore_missing.md
+- docs/users/configuration/index.md
+- docs/users/configuration/kramdown_fix.md
+- docs/users/configuration/relative_urls.md
+- docs/users/configuration/suppress_warnings.md
+- docs/users/index.md
+- docs/users/installation.md
+- docs/users/liquid_tag/argument_reference/alternate_images.md
+- docs/users/liquid_tag/argument_reference/attributes.md
+- docs/users/liquid_tag/argument_reference/base_image.md
+- docs/users/liquid_tag/argument_reference/crop.md
+- docs/users/liquid_tag/argument_reference/link.md
+- docs/users/liquid_tag/argument_reference/preset.md
+- docs/users/liquid_tag/argument_reference/readme.md
+- docs/users/liquid_tag/examples.md
+- docs/users/liquid_tag/index.md
+- docs/users/notes/git_lfs.md
+- docs/users/notes/github_pages.md
+- docs/users/notes/html_attributes.md
+- docs/users/notes/index.md
+- docs/users/notes/input_checking.md
+- docs/users/notes/kramdown_bug.md
+- docs/users/notes/managing_images.md
+- docs/users/notes/migration.md
+- docs/users/presets/cropping.md
+- docs/users/presets/default.md
+- docs/users/presets/examples.md
+- docs/users/presets/fallback_image.md
+- docs/users/presets/html_attributes.md
+- docs/users/presets/image_formats.md
+- docs/users/presets/image_quality.md
+- docs/users/presets/index.md
+- docs/users/presets/link_source.md
+- docs/users/presets/markup_formats/fragments.md
+- docs/users/presets/markup_formats/javascript_friendly.md
+- docs/users/presets/markup_formats/readme.md
+- docs/users/presets/markup_formats/standard_html.md
+- docs/users/presets/media_queries.md
+- docs/users/presets/nomarkdown_override.md
+- docs/users/presets/pixel_ratio_srcsets.md
+- docs/users/presets/width_height_attributes.md
+- docs/users/presets/width_srcsets.md
 - jekyll-picture-tag.gemspec
 - jekyll_picture_tag.gemspec
 - lib/jekyll-picture-tag.rb

data/docs/_layouts/directory.html

@@ -1,32 +0,0 @@
----
-layout: default
----
-
-<link href="{{ site.baseurl }}/assets/style.css" rel="stylesheet" type="text/css">
-
-<ul class="directory">
-  <li><a href="{{ site.baseurl }}/">Quick Start</a></li>
-  <li><a href="{{ site.baseurl }}/installation">Installation</a></li>
-  <li><a href="{{ site.baseurl }}/usage">Usage</a></li>
-  <li><a href="{{ site.baseurl }}/global_configuration">Global Settings</a></li>
-  <li><a href="{{ site.baseurl }}/presets">Writing Presets</a></li>
-  <li><a href="{{ site.baseurl }}/example_presets">Example Presets</a></li>
-  <li><a href="{{ site.baseurl }}/output">Output Formats</a></li>
-  <li><a href="{{ site.baseurl }}/notes">Notes and FAQ</a></li>
-  <li><a href="{{ site.baseurl }}/contributing">Contributing</a></li>
-  <li><a href="{{ site.baseurl }}/releases">Release History</a></li>
-</ul>
-
-<hr />
-
-{{ content }}
-
-<script>
-  const navItems = Array.from(document.querySelectorAll('ul.directory li'))
-  const currentPath = window.location.toString()
-  const activeItem = navItems.find(function(item) {
-    return item.firstChild.href == currentPath
-  })
-
-  activeItem.classList.add('active')
-</script>

data/docs/assets/style.css

@@ -1,31 +0,0 @@
-  @media (max-width: 600px) {
-    ul.directory {
-      flex-direction: column;
-      align-items: center;
-    }
-  }
-
-  ul.directory {
-    display: flex;
-    flex-wrap: wrap;
-    justify-content: center;
-    list-style: none;
-    padding-left: 0;
-    flex-grow: 0;
-  }  
-
-  ul.directory li {
-    margin: .3em;
-  }
-
-  ul.directory a {
-    line-height: 2;
-    padding: 8px 20px;
-  }
-
-  li.active a {
-    border-radius: 3px;
-    background-color: #007edf;
-    color: #fff;
-    box-shadow: 2px 2px 3px #999;
-  }

data/docs/contributing.md

@@ -1,109 +0,0 @@
----
----
-# Contributing
-
-Bug reports, feature requests, and feedback are very welcome, either through github issues or via
-email: robert@buchberger.cc 
-
-Pull requests are encouraged! I'm happy to answer questions and provide assistance along the way.
-Don't let any of the recommendations/requests in this guide stop you from submitting one.
-
-## Setup
-
-It's pretty standard:
-
-```
-$ git clone git@github.com:rbuchberger/jekyll_picture_tag.git
-$ cd jekyll_picture_tag
-$ bundle install
-```
-
-## Testing
-
-You probably only need to use docker if it's inconvenient to install ImageMagick 7.
-
-### Bare Metal
-
-`rake test` runs the test suite (both unit tests and integration tests). Ignore the mini_magick
-`method redefined` warnings (unless you know how to fix them?) 
-
-`rake unit` runs just the unit tests, while `rake integration` runs the integration tests. The unit
-test coverage isn't stellar, but both unit and integration tests together hit 100%.
-
-Speaking of coverage, simplecov is set up -- you'll get a measurement of coverage in the test output
-and a nice report in the `coverage` directory. I'd like to move to mutation based coverage testing,
-but that's a project for another day.
-
-The tests do output a few images to the `/tmp/` directory, which I'm pretty sure means it won't work
-on Windows. This is fixable if there is a need, so if that gets in your way just ask.
-
-`rake rubocop` checks code formatting, `rake rubocop:auto_correct` will try to fix any rubocop
-issues, if possible.
-
-`rake` will run all tests and rubocop.
-
-### Docker
-
-The following commands will build and run the tests inside a docker image. This is useful if it's
-inconvenient to install ImageMagick 7, or to ensure the Travis CI build will succeed:
-
-```
-$ docker build . -t jpt
-$ docker run -t jpt
-```
-
-## Docs
-
-I think one of the biggest opportunities for improvement in this plugin is its documentation. I'd
- really love help here, and all you need to know is markdown.
-
-It runs on github pages, which is based on jekyll. You can preview as you edit:
-
-0. Follow setup instructions above
-1. `$ cd docs`
-2. `$ bundle install`
-3. `$ bundle exec jekyll serve`
-4. In a web browser, navigate to `localhost:4000/jekyll_picture_tag/`
-
-## Code Guidelines
-
-* Generally, go for straightforward and readable rather than terse and clever. I'm not actually a
-  very good programmer; I need simple code that's easy to understand.
-
-* Refactoring is welcome, especially in the name of the previous point.
-
-* I'm very reluctant to introduce breaking changes to configuration settings. This rule isn't
-  absolute, but I'm not going to do it without a good reason.
-
-* I've been using 80 characters for code and 100 characters for documentation.
-
-* Don't disable cops without strong justification.
-
-* I generally try to write tests before writing code, especially when fixing bugs. This
-  gives us some confidence that what we think we're testing and what we're actually testing aren't
-  too different.
-
-## Hard rules
-
-These aren't the rules for submitting a pull request, these are the rules for merging into master.
-I'm thrilled to receive any help at all, and I'm more than happy to help with meeting these
-criteria:
-
-* Liquid tag syntax can only be extended; no breaking changes. I'm not willing to force
-  users to dig through their entire site and change every picture tag in order to update to the
-  latest version.
-
-* Maintain "no configuration required" - a new user must be able to add JPT to their gemfile, bundle
-  install, and start writing picture tags in their site without touching a yml file.
-
-* 100% test coverage (Meaning that when running the unit and integration tests together, every line
-  of code in the `lib` folder must run at least once.)
-
-* No failing tests
-
-* No rubocop warnings
-
-### Thanks!
-
-As I said, don't let any of the rules & guidelines scare you away. They're the rules for merging
-into master, not submitting a pull request. I'm thrilled to receive any help at all.

data/docs/example_presets.md

@@ -1,116 +0,0 @@
----
----
-# /_data/picture.yml
-
-These are example settings- I mostly made them up off the top of my head. You
-probably don't want to just copy-paste them. The full documentation
-for these can be found [here]({{ site.baseurl }}/presets).
-
-```yml
-
-# Media presets are just named css media queries, used in several places:
-# - To specify alternate source images (for art direction)
-# - To build the 'sizes' attribute
-# - When given alternate source images, specify which sizes to generate.
-media_presets:
-  wide_desktop: 'min-width: 1801px'
-  desktop: 'max-width: 1800px'
-  wide_tablet: 'max-width: 1200px'
-  tablet: 'max-width: 900px'
-  mobile: 'max-width: 600px'
-
-# Markup presets allow you to group settings together, and select one of them by
-# name in your jekyll tag. All settings are optional.
-markup_presets:
-
-  default:
-    # What form the output markup should take:
-    markup: auto
-
-    # Must be an array, and order matters. Defaults to just 'original', which
-    # does what you'd expect.
-    formats: [webp, original]
-
-    # Must be an array: which image sizes (width in pixels) to generate (unless
-    # directed otherwise below). If not specified, will use sensible default
-    # values.
-    widths: [200, 400, 800, 1600]
-
-    # Alternate source images (for art direction) are associated with media
-    # query presets. Here, you can optionally specify a different set of sizes
-    # to generate for those alternate source images.  This is how you avoid
-    # generating a 1600 pixel wide image that's only shown on narrow screens.
-    # Must be arrays.
-    media_widths: 
-      mobile: [200, 400, 600] 
-      tablet: [400, 600, 800]
-
-    # For building the 'sizes' attribute on img and source tags. specifies how
-    # wide the image will be when a given media query is true. Note that every
-    # source in a given <picture> tag will have the same associated sizes
-    # attribute.
-    sizes: 
-      mobile: 100vw
-      tablet: 80vw
-
-    # Specifies an optional, unconditional size attribute. Can be given alone,
-    # or if specified in combination with 'sizes' below, will be given last
-    # (when no media queries apply).
-    size: 800px
-
-    # Specify the properties of the fallback image. If not specified, will
-    # return a 900 pixel wide image in the original format.
-    fallback_width: 800
-    fallback_format: original
-
-    # Add HTML attributes. 'parent' will go to the <picture> tag if it's there,
-    # otherwise the 'img' tag.
-    attributes:
-      parent: 'data-downloadable="true"'
-      picture: 'class="awesome" data-volume="11"'
-      img: 'class="some-other-class"'
-      a: 'class="image-link"'
-
-    # This will wrap images in a link to the original source image. Obviously
-    # your source images will need to be part of the deployed site for this to
-    # work. If you have issues such as mangled HTML or extra {::nomarkdown}
-    # tags floating around, see docs/notes.md
-    link_source: true
-
-  # This is an example of how you would create a 'multiplier' based srcset;
-  # useful when an image will always be the same size on all screens (icons,
-  # graphics, thumbnails, etc), but you'd like to supply higher resolution
-  # images to devices with higher pixel ratios.
-  icon:
-    base_width: 20 # How wide the 1x image should be
-    pixel_ratios: [1, 1.5, 2]
-    fallback_width: 20
-    attributes:
-      img: 'class="icon"'
-
-  # Here's an example of how you'd configure jekyll-picture-tag to work with
-  # something like lazyload:
-  # https://github.com/verlok/lazyload
-  lazy:
-    # data_auto gives you data-src, data-srcset, and data-sizes instead of src,
-    # srcset, and sizes:
-    markup: data_auto
-    formats: [webp, original]
-    widths: [200, 400, 600, 800]
-    noscript: true # add a fallback image inside a <noscript> tag.
-    attributes: 
-      img: class="lazy"
-
-  # This is an example of how you'd get generated image and a URL, and nothing
-  # else.
-  direct:
-    markup: direct_url
-    fallback_format: webp # Default original
-    fallback_width: 600 # Default 800
-
-  # Here's a naked srcset. Doesn't even give you the surrounding quotes.
-  srcset:
-    markup: naked_srcset
-    formats: [webp] # must be an array, even if it only has one item
-
-```