jekyll_picture_tag 1.10.1 → 1.14.0

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,361 +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.
-
-* **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.