jekyll_picture_tag 1.11.0 → 1.12.0

data/docs/global_configuration.md

@@ -1,173 +0,0 @@
----
----
-# Global Configuration
-
-**All configuration is optional**. If you are happy with the defaults, you don't have to touch a
-single yaml file.
-
-Global settings are stored under the `picture:` key in `/_config.yml`.
-
-**Example config:**
-
-```yml
-picture:
-  source: "assets/images/fullsize"
-  output: "assets/images/generated"
-```
-
-* **Source Image Directory**
-
-  *Format:* `source: (directory)`
-
-  *Example:* `source: images/`
-
-  *Default:* Jekyll site root.
-
-  To make writing tags easier you can specify a source directory for your assets. Base images in the
-  tag will be relative to the `source` directory, which is relative to the Jekyll site root.
-
-  {% raw %}
-  For example, if `source` is set to `assets/images/_fullsize`, the tag
-  `{% picture enishte/portrait.jpg --alt An unsual picture %}` will look for a file at
-  {% endraw %}
-  `assets/images/_fullsize/enishte/portrait.jpg`.
-
-* **Destination Image Directory**
-
-    *Format:* `output: (directory)`
-
-    *Example:* `output: resized_images/`
-
-    *Default*: `generated/`
-
-  Jekyll Picture Tag saves resized, reformatted images to the `output` directory in your compiled
-  site. The organization of your `source` directory is maintained.
-
-  This setting is relative to your compiled site, which means `_site` unless you've changed it.
-
-* **Suppress Warnings**
-
-    *Format:* `suppress_warnings: (true|false)`
-
-    *Example:* `suppress_warnings: true`
-
-    *Default*: `false`
-
-  Jekyll Picture Tag will warn you in a few different scenarios, such as when your base image is
-  smaller than one of the sizes in your preset. (Note that Jekyll Picture Tag will never resize an
-  image to be larger than its source). Set this value to `true`, and these warnings will not be shown.
-
-* **Continue build with missing source images**
-
-    *Format:* `ignore_missing_images: (boolean|environment name|array of environments)`
-
-    *Example:* `ignore_missing_images: [development, testing]`
-
-    *Default:* `false`
-
-  Normally, JPT will raise an error if a source image is missing, causing the entire site build to
-  fail. This setting allows you to bypass this behavior and continue the build, either for certain
-  build environments or all the time. I highly encourage you to set this to `development`, and set
-  the jekyll build environment to `production` when you build for production so you don't shoot
-  yourself in the foot (publish a site with broken images). You can read more about Jekyll
-  environments [here](https://jekyllrb.com/docs/configuration/environments/).
-  
-* **Use Relative Urls**
-
-    *Format:* `relative_url: (true|false)`
-
-    *Example:* `relative_url: false`
-
-    *Default*: `true`
-
-  Whether to use relative (`/generated/test(...).jpg`) or absolute
-  (`https://example.com/generated/test(...).jpg`) urls in your src and srcset attributes.
-
-* **Use a CDN Url**
-
-    *Format:* `cdn_url: (url)`
-
-    *Example:* `cdn_url: https://cdn.example.com`
-
-    *Default*: none
-
-    Use for images that are hosted at a different domain or subdomain than the Jekyll site root. Overrides
-    `relative_url`. Keep reading, the next option is important.
-
-* **CDN build environments**
-
-    *Format:* `cdn_environments: (array of strings)`
-
-    *Example:* `cdn_environments: ['production', 'staging']`
-
-    *Default*: `['production']`
-
-    It's likely that if you're using a CDN, you may not want to use it in your local development environment. This
-    allows you to build a site with local images while in development, and still push to a CDN when you build for
-    production by specifying a different [environment](https://jekyllrb.com/docs/configuration/environments/). 
-
-    **Note that the default jekyll environment is `development`**, meaning that if you only set `cdn_url` and run
-    `jekyll serve` or `jekyll build`, nothing will change. You'll either need to run `JEKYLL_ENV=production bundle exec
-    jekyll build`, or add `development` to this setting.
-
-* **Kramdown nomarkdown fix**
-
-  *Format:* `nomarkdown: (true|false)`
-
-  *Example:* `nomarkdown: false`
-
-  *Default:* `true`
-
-  Whether or not to surround j-p-t's output with a `{::nomarkdown}..{:/nomarkdown}` block when called
-  from within a markdown file. 
-
-  This setting is overridden by the same setting in a preset. See [the notes]({{ site.baseurl
-  }}/notes) for more detailed information. 
-
-* **Fast Build**
-
-  *Format:* `fast_build: (true|false|environment|array of environments)`
-
-  *Examples:* 
-
-    - `fast_build: true`
-
-    - `fast_build: development`
-
-    - `fast_build: [development, staging]`
-
-  *Default:* `false`
-
-  Makes a tradeoff: Speeds repeated build times for sites with many images, by assuming that the
-  filename alone is enough to uniquely identify a source image. This doesn't speed up image
-  generation, just detection of whether or not it's necessary.
-
-  Ordinarily, JPT generates an MD5 hash for every source image, every site build. This ensures that
-  if you replace one image with another, but keep the filename the same, JPT will correctly generate
-  images for the new file. If you have many large images and/or limited hardware, this can take some
-  time and make the development process painful. Enable this setting to skip MD5 hash checking on
-  existing generated images (most of the time), and just assume that if the filename, format, and
-  width match then it's the right one. If there are multiple possible matches (resulting from
-  leftover generated images from previous filename replacements), it'll compute a hash instead of
-  guessing randomly.
-
-* **Disable Jekyll Picture Tag**
-
-  *Format:* `disabled: (true|false|environment|array of environments)`
-
-  *Examples:* 
-
-    - `disabled: true`
-
-    - `disabled: development`
-
-    - `disabled: [development, staging]`
-
-  *Default:* `false`
-
-  Disable image and markup generation entirely. Useful for debugging, or to speed up site builds
-  when you're working on something else.
-
-  Hint: If you're going to toggle this on and off frequently, you might just use an environment
-  variable. Set this to something like `nopics`, and then start the Jekyll server with something
-  like `JEKYLL_ENV=nopics bundle exec jekyll serve` when you don't want image generation.

data/docs/installation.md

@@ -1,45 +0,0 @@
----
----
-
-# Installation
-
-- Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group:
-
-  ```ruby
-  group :jekyll_plugins do
-    gem 'jekyll_picture_tag'
-  end
-  ```
-
-- Run `$ bundle install`
-
-- See if you have ImageMagick with `$ convert --version`. You should see something like this:
-
-  ```
-  ~ $ convert --version
-  Version: ImageMagick 7.0.8-14 Q16 x86_64 2018-10-31 https://imagemagick.org
-  Copyright: © 1999-2018 ImageMagick Studio LLC License: https://imagemagick.org/script/license.php
-  Features: Cipher DPC HDRI OpenMP Delegates (built-in): bzlib fontconfig freetype jng jp2 jpeg lcms
-  lzma pangocairo png tiff webp xml zlib
-  ```
-
-  If you get a 'command not found' error, you'll need to install it. Most package managers know about
-  ImageMagick, otherwise it can be found [here](https://imagemagick.org/script/download.php).
-
-- **Note webp under delegates.** This is required if you want to generate webp files. Any image format
-  you want to handle will require an appropriate delegate; You may have to install additional packages
-  to accomplish this.
-
-## Cropping and Imagemagick
-
-Cropping to an aspect ratio depends on ImageMagick 7+. Ubuntu, somewhat annoyingly, only offers
-version 6 in its official repositories. This matters even if you don't run Ubuntu, because many
-build & deployment services you might use (including Netlify and Travis CI) do.
-
-If you'd like to use both the cropping feature and such a service, or it's inconvenient to install
-version 7 in your development environment, you will likely want to build your site in a docker
-container. The Alpine Linux repos include version 7, so you'll want an Alpine Linux based image
-rather than an Ubuntu based one. Conveniently this includes the [offical Jekyll
-image](https://hub.docker.com/r/jekyll/jekyll).
-
-Once I work out how to actually do that, I'll add some guidance here.

data/docs/notes.md

@@ -1,91 +0,0 @@
----
----
-# Notes and FAQ
-
-* #### Github Pages?
-
-  Github Pages only allows a very short whitelist of plugins, which sadly does not include JPT. You
-  can either run it locally, then commit and push the generated files (rather than the source
-  files), or just host it some other way. I recommend Netlify.
-
-* #### HTML attributes
-
-  Jekyll Picture Tag has comprehensive attribute support for all generated HTML. You can add
-  attributes both through the [liquid tag]({{ site.baseurl }}/usage), and the [preset]({{
-  site.baseurl }}/presets) (scroll down a bit).
-
-* ### Input checking
-
-  Jekyll Picture Tag is very trusting. It doesn't do much checking of your inputs, and it does not
-  fail gracefully if you for example pass it a string when it expects an array. It's on the to-do
-  list, but for now if you get cryptic errors then double-check your settings and tag arguments.
-
-* ### Git LFS
-
-  I'm Putting this here because it bit me: If you want to use git LFS, make sure that your hosting
-  provider makes those images available during the build process.  Netlify, for example, does not.
-  You won't find this out until you have gone through the entire migration process and try to deploy
-  for the first time.
-
-
-* #### Extra {::nomarkdown} tags or mangled HTML?
-
-  **TLDR up front:** There's a bug involving `<picture>` tags wrapped in `<a>` tags which is not in my
-  power to fix.
-
-  * If you're getting extra `{::nomarkdown}` tags floating around your images, add `nomarkdown:
-    false` to either the relevant preset or under `picture` in `_config.yml`. 
-
-  * If you're getting mangled HTML when trying to wrap images with anchor tags, add `nomarkdown:
-    true` to the preset. 
-  
-  **What's going on here:**
-
-  Kramdown is Jekyll's default markdown parser. Kramdown gets grumpy when you give it a block level
-  element (such as a `<picture>`) surrounded by a span level element (such as an `<a>`), and horribly
-  mangles it. The fix for this is to tell Kramdown to chill with a `{::nomarkdown}..{:/nomarkdown}`
-  wrapper.
-
-  Jekyll Picture Tag can be called from many different places: a markdown file, an HTML file, an HTML
-  layout for a markdown file, and an HTML include, to name a few. JPT tries its best to determine
-  whether its output will be parsed by Kramdown or not, but Jekyll itself doesn't make this
-  particularly easy which results in some false positives. (The one I'm most aware of is when a
-  markdown file uses an HTML layout which includes a picture tag.) 
-
-  Unfortunately, I don't see an easy way to fix this. We've gotten this far mostly by trial and error.
-  I'll continue to work on improving the autodetection, but you can override this behavior explicitly. 
-
-  **The fix:**
-
-  By default, JPT will add a `{::nomarkdown}` tag if all of the following are true:
-  * It thinks it's called from a markdown page
-  * The image will be wrapped in an anchor tag (i.e. `link_source_image:` or a `--link` parameter)
-  * This behavior hasn't been explicitly disabled. 
-
-  You can disable nomarkdown tags globally by setting `nomarkdown: false` under the `picture:` key in
-  `_config.yml`.
-
-  You can enable or disable markdown tags per preset by adding `nomarkdown: true|false` to them.
-  **This setting overrides everything else, both JPT autodetection and the global setting.**
-
-* ### Managing Generated Images
-
-  Jekyll Picture Tag creates resized versions of your images when you build the site. It uses a
-  smart caching system to speed up site compilation, and re-uses images as much as possible.
-  Filenames take the following format:
-
-  `(original name without extension)-(width)-(source hash).(filetype)`
-
-  Source hash is the first 5 characters of an md5 checksum of the source image.
-
-  Try to use a base image that is larger than the largest resized image you need. Jekyll Picture Tag
-  will warn you if a base image is too small, and won't upscale images.
-
-  By specifying a `source` directory that is ignored by Jekyll you can prevent huge base images from
-  being copied to the compiled site. For example, `source: assets/images/_fullsize` and `output:
-  generated` will result in a compiled site that contains resized images but not the originals. Note
-  that this will break source image linking, if you wish to enable it. (Can't link to images that
-  aren't public!)
-
-  The `output` directory is never deleted by Jekyll. You may want to empty it once in awhile, to
-  clear out unused images. 

data/docs/output.md

@@ -1,63 +0,0 @@
----
----
-
-# Output Formats
-
-This is a listing of the various text arrangements that JPT can give you. Select one by setting
-`markup:` in the relevant [markup preset]({{ site.baseurl }}/presets).
-
-Example:
-
-```yml
-# /_data/picture.yml
-
-markup_presets:
-  my_preset:
-    markup: data_auto
-```
-
-## Standard HTML:
-
-- **`picture`:** `<picture>` element surrounding a `<source>` tag for each required srcset, and a
-  fallback `<img>`.
-
-- **`img`:** output a single `<img>` tag with a `srcset` entry.
-
-- **`auto`:** Supply an img tag when you have only one srcset, otherwise supply a picture tag.
-
-## Javascript Friendly:
-
-- **`data_picture`, `data_img`, `data_auto`:** Analogous to their counterparts above, 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).
-
-#### Special Options
-
-The following preset configuration settings only apply to the `data_` output formats.
-
-- **noscript**
-
-  _Format:_ `noscript: true|false`
-
-  _Default:_ `false`
-
-  Include a basic `img` fallback within a `<noscript>` tag, giving your javascript-disabled users
-  something to look at.
-
-- **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. (Useful for interfacing nicely with all the
-  various JS image libraries out there.)
-
-## Fragments:
-
-- **`direct_url`**: Generates an image and returns only its url. Uses `fallback_` properties (width
-  and format).
-
-- **`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.

data/docs/presets.md

@@ -1,391 +0,0 @@
----
----
-
-# Writing Presets
-
-Presets are named collections of settings that determine basically everything about JPT's output.
-They are stored in `_data/picture.yml`, to avoid cluttering `_config.yml`. You will have to create
-this file, and probably the `_data/` directory as well.
-
-Here's an [example data file]({{ site.baseurl }}/example_presets).
-
-Any settings which are specific to particular output formats are documented on the [output
-formats]({{site.baseurl}}/output) page.
-
-## Required Knowledge
-
-If you don't know the difference between resolution switching and art direction, stop now and read
-the [MDN Responsive Images
-guide](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)
-in detail. Ideally, play around with a basic HTML file, a few test images, and a few different
-browser widths until you understand it.
-
-## Media Presets
-
-_Format:_
-
-```yml
-media_presets:
-  (name): (css media query)
-  (name): (css media query)
-  (...)
-
-```
-
-_Example:_
-
-```yml
-media_presets:
-  desktop: "min-width: 1200px"
-```
-
-These are named media queries for use 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 around the media queries, because yml gets confused by colons.
-
-## Markup Presets
-
-_Format:_
-
-```yml
-markup_presets:
-  (name):
-    (option): (setting)
-    (option): (setting)
-    (...)
-  (...)
-```
-
-_Example:_
-
-```yml
-markup_presets:
-  default:
-    formats: [webp, original]
-    widths: [200, 400, 800, 1600]
-    link_source: true
-  lazy:
-    markup: data_auto
-    widths: [200, 400, 800, 1600]
-    link_source: true
-    noscript: true
-```
-
-Each entry is a pre-defined collection of settings to build a given chunk of text (usually HTML) and
-its respective images. You can select one as the first argument given to the tag:
-
-{% raw %}
-`{% picture my-preset image.jpg %}`
-{% endraw %}
-
-The `default` preset will be used if none is specified. A preset name can't contain a `.` (period).
-
-#### A Note on srcsets
-
-For images that are different sizes on different screens (most images), use a width-based srcset
-(which is the default). Specify a `widths` setting (or don't, for the default set), and optionally
-the `sizes` and `size` settings.
-
-Use a multiplier-based srcset when the image will always be the same size, regardless of screen
-width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratios` and `base_width`.
-
-### Settings reference
-
-- **Markup format**
-
-  _Format:_ `markup: (setting)`
-
-  _Default_: `auto`
-
-  Defines what format the generated text will take. They are documented [here]({{ site.baseurl }}/output).
-
-* **Image Formats**
-
-  _Format:_ `format: [format1, format2, (...)]`
-
-  _Example:_ `format: [webp, original]`
-
-  _Default_: `original`
-
-  Array (yml sequence) of the image formats you'd like to generate, in decreasing order of
-  preference. Browsers will render the first format they find and understand, so **If you put jpg
-  before webp, your webp images will never be used**. `original` does what you'd expect. To supply
-  webp, you must have an imagemagick webp delegate installed. (Most package managers just name it
-  'webp')
-
-  _Supported formats are anything which imagemagick supports, and has an installed delegate. See a
-  list by running `$ convert --version`_
-
-* **Widths**
-
-  _Format:_ `widths: [integer, integer, (...)]`
-
-  _Example:_ `widths: [600, 800, 1200]`
-
-  _Default_: `[400, 600, 800, 1000]`
-
-  Array of image widths to generate, in pixels. For use when you want a width-based srcset
-  (`srcset="img.jpg 800w, img2.jpg 1600w"`).
-
-* **Media_widths**
-
-  _Format:_
-
-  ```yml
-  media_widths:
-    (media preset 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.
-
-* **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. If you set this, you must also
-  give a `base_width`.
-
-  Set this when you want a multiplier based srcset (example: `srcset="img.jpg 1x, img2.jpg 2x"`).
-
-* **Base Width**
-
-  _Format:_ `base_width: integer`
-
-  _Example:_ `base_width: 100`
-
-  When using pixel ratios, you must supply a base width. This sets how wide the 1x image should be.
-
-* **Crop & Media Crop**
-
-  _Format:_
-
-  ```yml
-    crop: (geometery)
-    media_crop:
-    (media_preset): (geometry)
-    (media_preset): (geometry)
-    (...)
-  ```
-
-  _Example:_
-
-  ```yml
-  crop: 16:9
-  media_crop:
-    tablet: 3:2
-    mobile: 1:1
-  ```
-
-  **Check the [ installation guide ](installation) before using this feature.**
-
-  Crop geometry, given either generally or for specific media presets. The hierarchy is:
-  `tag argument` > `media_crop:` > `crop:`.
-
-  This setting accepts the same arguments as the `crop geometry` [tag parameter](usage).
-
-
-* **Gravity & Media_gravity**
-
-  ```yml
-    crop: (gravity)
-    media_crop:
-    (media_preset): (gravity)
-    (media_preset): (gravity)
-    (...)
-  ```
-
-  _Example:_
-
-  ```yml
-  crop: north
-  media_crop:
-    tablet: east
-    mobile: southwest
-  ```
-
-  Crop gravity, given either generally or for specific media presets. The hierarchy is:
-  `tag argument` > `media_crop:` > `crop:` > `center` (default).
-
-  This setting accepts the same arguments as the `crop gravity` [tag parameter](usage).
-
-* **Quality**
-
-  _Format:_ `quality: 0 <= integer <= 100`
-
-  _Example:_ `quality: 80`
-
-  _Default:_ `75`
-
-  This allows you to specify an image compression level for all image formats (where it makes sense,
-  anyway). The next option allows you to set them per format.
-
-* **Format Quality**
-
-  _Format:_
-
-  ```yml
-  format_quality:
-    (format): 0 <= integer <= 100
-    (...)
-  ```
-
-  _Example:_
-
-  ```
-  format_quality:
-    jpg: 75
-    png: 65
-    webp: 55
-  ```
-
-  _Default:_ quality setting (above)
-
-  This allows you to specify quality settings for various image formats, allowing you to take
-  advantage of webp's better compression algorithm without trashing your jpg images (for example).
-  If you don't give a setting for a particular format it'll fall back to the `quality` setting
-  above, and if you don't set _that_ it'll default to 75.
-
-* **Width & Height attributes (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 `width: 100%;` and `height: auto;` (or vice versa) set in CSS on the `<img>`
-      tags, or they will be stretched weirdly.
-    * 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.
-
-* **Arbitrary HTML Attributes**
-
-  _Format:_
-
-  ```yml
-  attributes:
-    (element): '(attributes)'
-    (...)
-  ```
-
-  _Example:_
-
-  ```yml
-  attributes:
-    img: 'class="soopercool" data-awesomeness="11"'
-    picture: 'class="even-cooler"'
-  ```
-
-  HTML attributes you would like to add. The same arguments are available here as in the liquid
-  tag: HTML element names, `alt:`, `link:`, and `parent:`. Unescaped double quotes cause problems
-  with yml, so it's recommended to surround them with single quotes.
-
-* **Fallback Width**
-
-  _Format:_ `fallback_width: (integer)`
-
-  _Example:_ `fallback_width: 800`
-
-  _Default_: `800`
-
-  Width of the fallback image.
-
-* **Fallback Format**
-
-  _Format:_ `fallback_format: (format)`
-
-  _Example:_ `fallback_format: jpg`
-
-  _Default_: `original`
-
-  Format of the fallback image
-
-* **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).
-
-* **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 the [notes]({{ site.baseurl }}/notes) for a detailed explanation.