jekyll_picture_tag 1.7.0 → 1.7.1

data/docs/usage.md

@@ -1,131 +1,113 @@
-# Liquid Tag Usage
+---
+---
+# How to use the Liquid Tag:
 
-The tag takes a mix of user input and pointers to configuration settings. The only required argument
-is the base image:
+## Format:
 
-`{% picture [preset] (source image) [alternate images] [attributes] %}`
+{% raw %}
+`{% picture [preset] (base image) [alternate images] [attributes] %}`
+{% endraw %}
 
-For filenames with spaces, you can either surround it with quotes (`"my image.jpg"`) or escape the
-space with a backslash (`"my\ image.jpg"`).
+The only required argument is the base image. Line breaks and extra spaces are fine, and you can
+use liquid variables anywhere.
 
 ## Examples:
 
+{% raw %}
 `{% picture example.jpg %}`
 
-`{% picture thumbnail example.jpg %}`
+`{% picture thumbnail example.jpg --alt Example Image %}`
+
+`{% picture example.jpg --picture class="attribute-demo" %}`
 
 `{% picture blog_index {{ post.image }} --link {{ post.url }} %}`
 
 `{% picture "some example.jpg" mobile: other\ example.jpg %}`
 
-```
+```md
 {% picture 
   hero 
   example.jpg 
-  mobile: example_cropped.jpg 
+  tablet: example_cropped.jpg
+  mobile: example_cropped_more.jpg 
   --alt Happy Puppy 
   --picture class="hero" 
   --link /
 %}
 ```
+{% endraw %}
 
 ## Argument reference
 
-* **Preset**
+Given in order:
 
-  *Format:* `(name of a markup preset described in _data/picture.yml)`
-
-  *Default:* `default`
+* **Preset**
 
-  Optionally specify a markup
-  [preset](https://github.com/rbuchberger/jekyll_picture_tag/wiki/Writing-Presets) to use, or leave
-  blank for the `default` preset.
+  Select a [markup preset]({{ site.baseurl }}/presets#markup-presets), or omit to use the `default` preset. Presets
+  are collections of settings that determine nearly everything about JPT's output, from the image
+  formats used to the exact format your markup will take.
 
-* **Source Image** (Required)
+* **Base Image** (Required)
 
-  *Format:* `(Image filename, relative to source setting in _config.yml)`
+  Can be any raster image (as long as you have the required ImageMagick delegate). Relative to
+  jekyll's root directory, or the `source` [setting]({{ site.baseurl }}/global_configuration) if you've configured it.
 
-  The base image that will be resized for your picture sources. Can be pretty much any raster image
-  (as long as imagemagick understands it).
+  For filenames with spaces, either use double quotes (`"my image.jpg"`) or a backslash (`my\
+  image.jpg`).
 
 * **Alternate images**
 
-    *Format:* `(media query preset): (image filename, relative to source directory)`
+    *Format:* `(media query preset): (filename) (...)`
 
     *Example:* `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
 
-  Optionally specify any number of alternate base images for given [media queries](#media-presets)
-  (specified in `_data/picture.yml`). This is one of of picture's strongest features, often referred
-  to as the [art direction use case](http://usecases.responsiveimages.org/#art-direction).
+  Optionally specify any number of alternate base images for given [screen
+  sizes]({{ site.baseurl }}/presets/#media-presets) (specified in `_data/picture.yml`). This is called [art
+  direction](http://usecases.responsiveimages.org/#art-direction), and is one of JPT's strongest
+  features.
 
   Give your images in order of ascending specificity (The first image is the most general). They will
-  be provided to the browser in reverse order, and it will select the first one with a media query
-  that evaluates true.
+  be provided to the browser in reverse order, and it will select the first one with an applicable
+  media query.
 
 * **Attributes**
 
-  Optionally specify any number of HTML attributes. These will be added to any attributes you've
-  set in a preset. They can take a few different formats:
+  Optionally specify any number of HTML attributes, or an href target. These will be added to any
+  attributes you've set in a preset.
 
-  ##### `--link`
+  * **`--link`**
 
-  *Format:* `--link (some url)`
+    *Format:* `--link (some url)`
 
-  *Examples*: `--link https://example.com`, `--link /blog/some_post/`
+    *Examples*: `--link https://example.com`, `--link /blog/some_post/`
 
-    Wrap the image in an anchor tag, with the `href` attribute set to whatever value you give it.
-    This will override automatic source image linking, if you have enabled it.
+      Wrap the image in an anchor tag, with the `href` attribute set to whatever value you give it.
+      This will override automatic source image linking, if you have enabled it.
 
-    **Note**: Don't disable the `nomarkdown` global setting if you would like do this within markdown
-    files and you are using Kramdown (Jekyll's default markdown parser.)
-  ##### `--alt`
-  
-  *Format:* `--alt (alt text)`
-
-  *Example:* `--alt Here is my alt text!`
+      **Note**: If you get either mangled HTML or extra {::nomarkdown} tags when using this, read
+      [here]({{ site.baseurl }}/notes).
 
-  Shortcut for `--img alt="..."`
+  * **`--alt`**
   
-  ##### `--(element)`
-
-  *Format:* `--(picture|img|source|a|parent) (Standard HTML attributes)`
-
-  *Example:* `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
+    *Format:* `--alt (alt text)`
 
-  Apply attributes to a given HTML element. Your options are:
+    *Example:* `--alt Here is my alt text!`
 
-  * `picture`
-  * `img`
-  * `source`
-  * `a` (anchor tag)
-  * `parent`
-
-  `--parent` will be applied to the `<picture>` if present, otherwise the `<img>`; useful when using
-    the `auto` output format.
-
-  ##### Old syntax
-
-  The old syntax is to just dump all attributes at the end:
-
-  `{% picture example.jpg alt="alt text" class="super-duper" %}`
+    Convenience shortcut for `--img alt="..."`
+  
+  * **`--(element)`**
 
-  This will continue to work. For backwards compatibility, behavior of previous versions is
-  maintained: all attributes specified this way are applied to the img tag.
+    *Format:* `--(picture|img|source|a|parent) (Standard HTML attributes)`
 
-#### Line breaks
-Line breaks and spaces are interchangeable, the following is perfectly acceptable:
+    *Example:* `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
 
-```
-{%
-  picture my-preset
-    img.jpg
-    mobile: alt.jpg
-    --alt Alt Text
-    --picture class="stumpy"
-%}
-```
-#### Liquid variables
+    Apply attributes to a given HTML element. Your options are:
 
-You can use liquid variables in a picture tag:
+    * `picture`
+    * `img`
+    * `source`
+    * `a` (anchor tag)
+    * `parent`
 
-`{% picture {{ post.featured_image }} --alt Our Project %}`
+    `--parent` will be applied to the `<picture>` if present, otherwise the `<img>`; useful when
+    using an `auto` output format.

data/jekyll_picture_tag.gemspec

@@ -35,11 +35,12 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 12.3'
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'solargraph'
 
   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'
+  spec.add_dependency 'objective_elements', '~> 1.1.1'
 
   spec.add_runtime_dependency 'jekyll', '< 5'
 end

data/lib/jekyll_picture_tag/instructions/html_attributes.rb

@@ -4,22 +4,28 @@ module PictureTag
     # sent to various elements.
     # Stored as a hash, with string keys.
     class HTMLAttributeSet
-      # Initialize with leftovers passed into the liquid tag
+      # Initialize with leftovers passed into the liquid tag. These leftovers
+      # (params) take the form of an array of strings, called words, which the
+      # tag parser has separated.
       def initialize(params)
-        @content = load_preset
+        @attributes = load_preset
 
         parse_params(params) if params
         handle_source_url
       end
 
       def [](key)
-        @content[key]
+        @attributes[key]
       end
 
       private
 
       def load_preset
-        PictureTag.preset['attributes'].dup || {}
+        # Shamelessly stolen from stackoverflow. Deep cloning a hash is
+        # surprisingly tricky! I could pull in ActiveSupport and get
+        # Hash#deep_dup, but for now I don't think it's necessary.
+
+        Marshal.load(Marshal.dump(PictureTag.preset['attributes'])) || {}
       end
 
       # Syntax this function processes:
@@ -30,10 +36,10 @@ module PictureTag
         words.each do |word|
           if word.match(/^--/)
             key = word.delete_prefix('--')
-          elsif @content[key]
-            @content[key] << ' ' + word
+          elsif @attributes[key]
+            @attributes[key] << ' ' + word
           else
-            @content[key] = word
+            @attributes[key] = word
           end
         end
       end
@@ -43,7 +49,7 @@ module PictureTag
 
         target = PictureTag.source_images.first.shortname
 
-        @content['link'] = ImgURI.new(target, source_image: true).to_s
+        @attributes['link'] = ImgURI.new(target, source_image: true).to_s
       end
     end
   end

data/lib/jekyll_picture_tag/version.rb

@@ -1,3 +1,3 @@
 module PictureTag
-  VERSION = '1.7.0'.freeze
+  VERSION = '1.7.1'.freeze
 end

data/readme.md

@@ -6,211 +6,33 @@ It's easy to throw an image on a webpage and call it a day. Doing justice to you
 it efficiently on all browsers and screen sizes is tedious and tricky. Tedious, tricky things should be
 automated.
 
-Jekyll Picture Tag is a liquid tag that adds responsive images to your [Jekyll](http://jekyllrb.com)
-static site. It automatically creates resized, reformatted source images, is fully configurable,
-implements sensible defaults, and solves both the art direction and resolution switching problems,
-with a little YAML configuration and a simple template tag. It offers several different output
-formats, and can be configured to work with JavaScript libraries such as
-[LazyLoad](https://github.com/verlok/lazyload).
+Jekyll Picture Tag adds responsive images to your [Jekyll](http://jekyllrb.com) static site. It
+automatically creates resized, reformatted source images, is fully configurable, implements sensible
+defaults, and solves both the art direction and resolution switching problems with a little YAML
+configuration and a simple template tag.
 
-## Documentation
-
-It's all in the [`docs`](docs/) folder:
-
-* [Installation](docs/installation.md)
-* [Usage](docs/usage.md)
-* [Global settings](docs/global_configuration.md)
-* [Presets](docs/presets.md)
-* [Other notes](docs/notes.md)
-* [Contribute](contributing.md)
-* [Release History](#release-history)
-* [License](LICENSE.txt)
-
-## Why use Jekyll Picture Tag?
+## Why use Responsive Images?
 
 **Performance:** The fastest sites are static sites, but when you plonk a 2mb picture of your dog at
-the top of a blog post you're throwing it all away.
+the top of a blog post you're throwing it all away.  Responsive images allow you to keep your site
+fast, without compromising image quality.
 
 **Design:** Your desktop image may not work well on mobile, regardless of its resolution. We often
 want to do more than just resize images for different screen sizes, we want to crop them or use a
 different image entirely.
 
-**Developer Sanity:** Image downloading starts before the browser has parsed your CSS and
-JavaScript; this gets them on the page *fast*, but it leads to some ridiculously verbose markup.
-To serve responsive images correctly, we must:
-
-- Generate, name, and organize the required images (formats \* resolutions \* source images)
-- Inform the browser about the image itself-- format, size, URI, and the screen sizes where it
-  should be used.
-- Inform the browser how large the space for that image on the page will be (which also probably
-  has associated media queries).
+## Why use Jekyll Picture Tag?
 
-It's a lot. It's tedious and complicated. Jekyll Picture Tag makes it easy.  
+**Developer Sanity:** If you want to serve multiple images in multiple formats and resolutions, you
+have a litany of markup to write and a big pile of images to generate. Jekyll Picture Tag is your
+responsive images minion - give it simple instructions and it'll handle the rest. 
 
 ## Features
 
-* Automatic generation of resized, converted image files.
+* Automatic generation and organization of resized image files in basically any format(s).
 * Automatic generation of complex markup in several different formats.
 * No configuration required, extensive configuration available.
-* `sizes` attribute assistance.
-* Optionally, automatically link to the source image. Or manually link to anywhere else, with just a
-  tag parameter!
-
-## Quick start / Demo
-
-**All configuration is optional.** Here's the simplest possible use case:
-
-Add j_p_t to your gemfile:
-
-```ruby
-group :jekyll_plugins do
-  gem 'jekyll_picture_tag'
-end
-```
-
-Run `bundle install`
-
-Put this liquid tag somewhere:
-
-`{% picture test.jpg %}`
-
-Get this in your generated site:
-
-```html
-<!-- Formatted for readability -->
-
-<img src="/generated/test-800-195f7d.jpg"
-  srcset="
-    /generated/test-400-195f7d.jpg   400w,
-    /generated/test-600-195f7d.jpg   600w,
-    /generated/test-800-195f7d.jpg   800w,
-    /generated/test-1000-195f7d.jpg 1000w
-    ">
-```
-
-### Look man, that's cool and all but I just want webp.
-
-Create `_data/picture.yml`, add the following:
-
-```yml
-markup_presets:
-  default:
-    formats: [webp, original]
-```
-
-If you get errors, make sure you have imagemagick installed with a webp delegate.
-
-### Here's a more complex example:
-
-```yml
-# _data/picture.yml
-
-media_presets:
-  mobile: 'max-width: 600px'
-
-markup_presets:
-  default:
-    widths: [600, 900, 1200]
-    formats: [webp, original]
-    sizes:
-      mobile: 80vw
-    size: 500px
-```
-
-Write this:
-
-`{% picture test.jpg mobile: test2.jpg --alt Alternate Text %}`
-
-Get this:
-
-```html
-<!-- Formatted for readability -->
-
-<picture>
-  <source
-    sizes="(max-width: 600px) 80vw, 600px"
-    media="(max-width: 600px)"
-    srcset="
-      /generated/test2-600-21bb6f.webp   600w,
-      /generated/test2-900-21bb6f.webp   900w,
-      /generated/test2-1200-21bb6f.webp 1200w
-    "
-    type="image/webp">
-  <source
-    sizes="(max-width: 600px) 80vw, 600px"
-    srcset="
-      /generated/test-600-195f7d.webp   600w,
-      /generated/test-900-195f7d.webp   900w,
-      /generated/test-1200-195f7d.webp 1200w
-    "
-    type="image/webp">
-  <source
-    sizes="(max-width: 600px) 80vw, 600px"
-    media="(max-width: 600px)"
-    srcset="
-      /generated/test2-600-21bb6f.jpg   600w,
-      /generated/test2-900-21bb6f.jpg   900w,
-      /generated/test2-1200-21bb6f.jpg 1200w
-    "
-    type="image/jpeg">
-  <source
-    sizes="(max-width: 600px) 80vw, 600px"
-    srcset="
-      /generated/test-600-195f7d.jpg   600w,
-      /generated/test-900-195f7d.jpg   900w,
-      /generated/test-1200-195f7d.jpg 1200w
-    "
-    type="image/jpeg">
-  <img src="/generated/test-800-195f7d.jpg" alt="Alternate Text">
-</picture>
-```
-
-Jekyll Picture Tag ultimately relies on [ImageMagick](https://www.imagemagick.org/script/index.php)
-for image conversions, so it must be installed on your system. There's a very good chance you
-already have it. If you want to build webp images, you will need to install a webp delegate for it
-as well.
 
-## Release History
+## Documentation:
 
-* 1.7.0 Aug 12, 2019
-  * Add support for setting generated image quality, either generally or specific to given
-    formats.
-  * Add support for spaces and other url-encoded characters in filenames
-  * Documentation restructure - Moved it out of the wiki, into the `docs` folder.
-  * Bugfix: Fallback image width will now be checked against source image width.
-  * Bugfix: Minor fix to nomarkdown wrapper output
-  * link_source will now target the base source image, rather than finding the biggest one.
-  * Remove fastimage dependency, add addressable dependency.
-  * Moderately significant refactoring and code cleanup 
-  * Decent set of tests added
-* 1.6.0 Jul  2, 2019:
-  * Missing Preset warning respects `data_dir` setting
-  * Add `continue_on_missing` option
-* 1.5.0 Jun 26, 2019: 
-  * better `{::nomarkdown}` necessity detection
-  * allow user to override `{::nomarkdown}` autodetection
-* 1.4.0 Jun 26, 2019:
-  * Rename gem from `jekyll-picture-tag` to `jekyll_picture_tag`, allowing us to use rubygems again.
-  * Add new output format: `naked_srcset`.
-* 1.3.1 Jun 21, 2019: Bugfix
-* 1.3.0 Jun  7, 2019:
-  * Initial compatibility with Jekyll 4.0
-  * bugfixes
-  * change to generated image naming-- The first build after this update will be longer, and you
-    might want to clear out your generated images.
-* 1.2.0 Feb  9, 2019:
-  * Add nomarkdown fix
-  * noscript option
-  * relative url option
-  * anchor tag wrappers
-* 1.1.0 Jan 22, 2019:
-  * Add direct_url markup format,
-  * auto-orient images before stripping metadata
-* 1.0.2 Jan 18, 2019: Fix ruby version specification
-* 1.0.1 Jan 13, 2019: Added ruby version checking
-* **1.0.0** Nov 27, 2018: Rewrite from the ground up. See the [migration guide](docs/migration.md).
-* 0.2.2 Aug  2, 2013: Bugfixes
-* 0.2.1 Jul 17, 2013: Refactor again, add Liquid parsing.
-* 0.2.0 Jul 14, 2013: Rewrite code base, bring in line with Jekyll Image Tag.
-* 0.1.1 Jul  5, 2013: Quick round of code improvements.
-* 0.1.0 Jul  5, 2013: Initial release.
+https://rbuchberger.github.io/jekyll_picture_tag/

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_picture_tag
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.7.1
 platform: ruby
 authors:
 - Robert Wierzbowski
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-12 00:00:00.000000000 Z
+date: 2019-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -124,6 +124,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: solargraph
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: addressable
   requirement: !ruby/object:Gem::Requirement
@@ -172,14 +186,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: 1.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: 1.1.1
 - !ruby/object:Gem::Dependency
   name: jekyll
   requirement: !ruby/object:Gem::Requirement
@@ -209,20 +223,26 @@ files:
 - ".gitignore"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".solargraph.yml"
 - ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - Rakefile
-- contributing.md
-- docs/examples/_config.yml
-- docs/examples/_data/picture.yml
-- docs/examples/post.md
+- 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/index.md
 - docs/installation.md
 - docs/migration.md
 - docs/notes.md
+- docs/output.md
 - docs/presets.md
-- docs/readme.md
+- docs/releases.md
 - docs/usage.md
 - jekyll-picture-tag.gemspec
 - jekyll_picture_tag.gemspec

data/docs/examples/_config.yml

@@ -1,10 +0,0 @@
-# Sample Jekyll Picture Tag settings
-# Note that all of these settings have sensible defaults. Don't just copy-paste
-# this into your _config.yml!
-picture:
-  source: assets/images/_fullsize
-  output: generated 
-  suppress_warnings: false
-  ignore_missing_images: [development, test]
-  cdn_url: cdn.example.com
-  cdn_environments: production

data/docs/examples/post.md

@@ -1,46 +0,0 @@
-```
----
-layout: post
-title: Tag examples
-image: img.jpg
----
-```
-
-- Standard image, default preset, with alt text:
-
-  `{% picture portrait.jpg --alt An unsual picture %}`
-
-- Select the `gallery` `markup_preset` (which you must define!):
-
-  `{% picture gallery portrait.jpg %} `
-
-- Specify html attributes:
-
-  `{% picture portrait.jpg --picture class="some classes" data-downloadable="true" %}`
-
-- Provide multiple source images for different screen sizes: (note that you must
-define the mobile `media_preset`):
-
-  `{% picture portrait.jpg mobile: portrait-cropped.jpg %}`
-
-- Wrap picture in a link to something: 
-
-  `{% picture portrait.jpg --link /profile.html %}`
-
-- Use liquid variables:
-
-  `{% picture {{ post.image }} %}`
-
-- Line breaks and indentation are fine:
-
-```
-  {% 
-    picture 
-      gallery
-      portrait.jpg
-      mobile: portrait-cropped.jpg
-      --picture class="portrait" data-downloadable="true"
-      --img data-awesomeness="11"
-      --alt Ugly Mug
-  %}
-```

data/docs/readme.md

@@ -1,23 +0,0 @@
-# Table of Contents
-
-* [Installation](installation.md)
-  - Get up and running
-
-* [Usage](usage.md)
-  - How to write liquid tags and actually put pictures on your site
-
-* [Global settings](global_configuration.md)
-  - Settings which apply to all presets
-
-* [Presets](presets.md)
-  - How to customize what images are generated and which markup is generated.
-
-* [Other notes](notes.md)
-  - Caveats and gotchas
-
-* [Contribute](/contributing.md)
-  - Appreciate the help!
-
-* [License](/LICENSE.txt)
-
-* [Release History](/readme.md#release-history)