jekyll_picture_tag 1.7.0 → 1.10.1

data/docs/output.md

@@ -0,0 +1,63 @@
+---
+---
+
+# 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,110 +1,62 @@
+---
+---
+
 # Writing Presets
 
-Presets 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.
+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.
 
-All settings are optional, moderately sensible defaults have been implemented.
+Here's an [example data file]({{ site.baseurl }}/example_presets).
 
-## Required Knowledge
+Any settings which are specific to particular output formats are documented on the [output
+formats]({{site.baseurl}}/output) page.
 
-If you don't understand responsive images, you won't know what to do with these settings. Jekyll
-Picture tag is basically a programmatic implementation of the [MDN Responsive Images
-guide](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
+## Required Knowledge
 
-If you don't know the difference between resolution switching and art direction, stop now and read it
+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.
 
-## Example settings
-
-A more thorough example can be found under `docs/examples/_data/picture.yml`.
-
-```yml
-
-# _data/picture.yml
-
-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:
-  default:
-    formats: [webp, original]
-    widths: [200, 400, 800, 1600]
-    media_widths:
-      mobile: [200, 400, 600]
-      tablet: [400, 600, 800]
-    size: 800px
-    sizes:
-      mobile: 100vw
-      desktop: 60vw
-    attributes:
-      picture: 'class="awesome" data-volume="11"'
-      img: 'class="some-other-class"'
-
-  icon:
-    base-width: 20
-    pixel_ratios: [1, 1.5, 2]
-
-  lazy:
-    markup: data_auto
-    formats: [webp, original]
-    widths: [200, 400, 600, 800]
-    noscript: true
-    attributes:
-      img: class="lazy"
-
-```
-
 ## Media Presets
 
-*Format:*
+_Format:_
 
 ```yml
 media_presets:
-  (name): (css media query)
   (name): (css media query)
   (name): (css media query)
   (...)
 
 ```
 
-*Example:*
+_Example:_
 
 ```yml
 media_presets:
-  desktop: 'min-width: 1200px'
+  desktop: "min-width: 1200px"
 ```
 
-These are named media queries for use in a few different places.
-
-Keys are names by which you can refer to the media queries supplied as their respective values.
-These are used for specifying alternate source images in your liquid tag, and for building the
-'sizes' attribute within your presets. Quotes are required around the media
-queries, because yml gets confused by free colons.
+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:*
+_Format:_
 
 ```yml
 markup_presets:
   (name):
-    (option): (setting)
-    (option): (setting)
-    (option): (setting)
-    (...)
-  (another name):
-    (option): (setting)
     (option): (setting)
     (option): (setting)
     (...)
+  (...)
 ```
 
-*Example:*
+_Example:_
 
 ```yml
 markup_presets:
@@ -119,73 +71,41 @@ markup_presets:
     noscript: true
 ```
 
-These are the 'presets' from previous versions, with different structure. Each entry is a
-pre-defined collection of settings to build a given chunk of HTML and its respective images. You
-can select one as the first argument given to the tag:
+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 the `.`, `:`,
-or `/` characters.
+The `default` preset will be used if none is specified. A preset name can't contain a `.` (period).
 
-#### A Note on srcsets, for the bad kids who didn't do the required reading.
+#### A Note on srcsets
 
-There are 2 srcset formats, one based on providing widths, the other based on providing multipliers.
+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.
 
-Width based srcsets look like this: `srcset="img.jpg 600w, img2.jpg 800w, img3.jpg 1000w"`. The
-`(number)w` tells the browser how wide that image file is. Browsers are smart, they know their
-device's pixel ratio, so in combination with the sizes attribute (if given, otherwise it assumes the
-image will be 100vw) they can select the best-fitting image for the space it will fill on the screen. This is generally the one you want to use.
+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`.
 
-Multiplier based srcsets look like this: `srcset="img.jpg 1x, img2.jpg 1.5x, img3.jpg 3x"`. The
-browser is less smart here; it looks at its own device's pixel ratio, compares it to the given
-multiplier, and picks the closest one. It doesn't consider anything else at all. Multiplier based
-srcsets are best used when the image will always be the same size, on all screen sizes.
+### Settings reference
 
-To use a width based srcset in a preset, specify a `widths` setting (or don't, for the default), and
-optionally the `sizes` and `size` settings.
+- **Markup format**
 
-To use a multiplier based srcset, set `pixel_ratios` and `base_width`.
+  _Format:_ `markup: (setting)`
 
-### Markup preset settings
+  _Default_: `auto`
 
-* **Markup format**
+  Defines what format the generated text will take. They are documented [here]({{ site.baseurl }}/output).
 
-  *Format:* `markup: (setting)`
-
-  *Default*: `auto`
-
-  Defines what format the generated HTML will take. Here are your options:
-
-  * `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.
-  * `data_picture`, `data_img`, `data_auto`: Analogous to their 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)
-  * `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). Useful with
-    libraries requiring more complex or customized markup. Note that the (image) `format` setting
-    must still be an array, even if you can only give it one value.
- 
 * **Image Formats**
 
-  *Format:* `format: [format1, format2, (...)]`  
+  _Format:_ `format: [format1, format2, (...)]`
 
-  *Example:* `format: [webp, original]`
+  _Example:_ `format: [webp, original]`
 
-  *Default*: `original`
-
-  *Supported formats are anything which imagemagick supports, including the
-  following:*
-  * jpg/jpeg
-  * png
-  * gif
-  * webp
-  * jxr
-  * jp2
+  _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
@@ -193,106 +113,84 @@ To use a multiplier based srcset, set `pixel_ratios` and `base_width`.
   webp, you must have an imagemagick webp delegate installed. (Most package managers just name it
   'webp')
 
-* **widths**
+  _Supported formats are anything which imagemagick supports, and has an installed delegate. See a
+  list by running `$ convert --version`_
+
+* **Widths**
 
-  *Format:* `widths: [integer, integer, (...)]`
+  _Format:_ `widths: [integer, integer, (...)]`
 
-  *Example:* `widths: [600, 800, 1200]`
+  _Example:_ `widths: [600, 800, 1200]`
 
-  *Default*: `[400, 600, 800, 1000]`
+  _Default_: `[400, 600, 800, 1000]`
 
-  Array of image widths to generate, in pixels. For use when you want a size-based srcset
+  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**
+* **Media_widths**
 
-    *Format:*
+  _Format:_
 
-    ```yml
-    media_widths:
-      (media preset name): [integer, integer, (...)]
-    ```
+  ```yml
+  media_widths:
+    (media preset name): [integer, integer, (...)]
+  ```
 
-    *Example:*
+  _Example:_
 
-    ```yml
-    media_widths:
-      mobile: [400, 600, 800]
-    ```
+  ```yml
+  media_widths:
+    mobile: [400, 600, 800]
+  ```
 
-    *Default:* Widths setting
+  _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.
 
-* **Fallback Width**
-
-    *Format:* `fallback_width: (integer)`             
-
-    *Example:* `fallback_width: 800`
-
-    *Default*: `800`
-
-  Width of the fallback image.
-
-* **Fallback Image**
-
-    *Format:*  `fallback_format: (format)`
-
-    *Example:* `fallback_format: jpg`
+* **Sizes**
 
-    *Default*: `original`
+  _Format:_
 
-  Format of the fallback image
+  ```yml
+  sizes:
+    (media preset): (CSS dimension)
+    (...)
+  ```
 
-* **Sizes**
+  _Example:_
 
-    *Format:*
-    ```yml
-    sizes:
-      (media preset): (CSS dimension)
-      (media preset): (CSS dimension)
-      (media preset): (CSS dimension)
-      (...)
-    ```
-
-    *Example:*
-    ```yml
-    sizes:
-      mobile: 80vw
-      tablet: 60vw
-      desktop: 900px
-    ```
+  ```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.
+  `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 
+  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.
 
-  The same sizes attribute is used for every source tag in a given picture tag. This causes some
-  redundant markup, specifying sizes for situations when an image will never be rendered, but it 
-  keeps things a bit simpler.
-
 * **Size**
 
-  *Format:* `size: (CSS Dimension)`
+  _Format:_ `size: (CSS Dimension)`
 
-  *Example:* `size: 80vw`
+  _Example:_ `size: 80vw`
 
-  Unconditional image width to give the browser (by way of the html sizes attribute), to be supplied
-  either alone or after all conditional sizes.
+  Unconditional `sizes` setting, to be supplied either alone or after all conditional sizes.
 
 * **Pixel Ratios**
 
-  *Format:* `pixel_ratios: [number, number, number (...)]`
+  _Format:_ `pixel_ratios: [number, number, number (...)]`
 
-  *Example:* `pixel_ratios: [1, 1.5, 2]`
+  _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`.
@@ -301,36 +199,87 @@ To use a multiplier based srcset, set `pixel_ratios` and `base_width`.
 
 * **Base Width**
 
-  *Format:* `base_width: integer`
+  _Format:_ `base_width: integer`
 
-  *Example:* `base_width: 100`
+  _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: integer <= 100`
+  _Format:_ `quality: 0 <= integer <= 100`
 
-  *Example:* `quality: 80`
+  _Example:_ `quality: 80`
 
-  *Default:* `75`
+  _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:* 
+  _Format:_
 
   ```yml
   format_quality:
-    (format): integer <= 100
-    (format): integer <= 100
-    (format): integer <= 100
+    (format): 0 <= integer <= 100
     (...)
   ```
 
-  *Example:*
+  _Example:_
 
   ```
   format_quality:
@@ -339,26 +288,24 @@ To use a multiplier based srcset, set `pixel_ratios` and `base_width`.
     webp: 55
   ```
 
-  *Default:* quality setting (above)
+  _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.
+  above, and if you don't set _that_ it'll default to 75.
 
 * **HTML Attributes**
 
-  *Format:*
+  _Format:_
 
   ```yml
   attributes:
-    (element): '(attributes)'
-    (element): '(attributes)'
     (element): '(attributes)'
     (...)
   ```
 
-  *Example:*
+  _Example:_
 
   ```yml
   attributes:
@@ -366,42 +313,49 @@ To use a multiplier based srcset, set `pixel_ratios` and `base_width`.
     picture: 'class="even-cooler"'
   ```
 
-  HTML attributes you would like to add.  The same arguments are available here as in the liquid
-  tag; element names, `alt:`, `url:`, and `parent:`. Unescaped double quotes cause problems with
-  yml, so it's recommended to surround them with single quotes.
+  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)`
 
-* **Noscript**
+  _Example:_ `fallback_width: 800`
 
-    *Format:* `noscript: (true|false)`
+  _Default_: `800`
 
-    *Example:* `noscript: true`
+  Width of the fallback image.
 
-    *Default:* `false`
+* **Fallback Format**
 
-  For use with the `data_` output formats. When true, will include a basic `img` fallback within a
-  `<noscript>` tag after the standard html. This allows you to use lazy loading or other javascript
-  image tools, without breaking all of your images for non-javascript-enabled users.
+  _Format:_ `fallback_format: (format)`
 
-* **Source Image Linking**
+  _Example:_ `fallback_format: jpg`
 
-    *Format:* `link_source: (true|false)`
+  _Default_: `original`
 
-    *Example:* `link_source: true`
+  Format of the fallback image
 
-    *Default:* `false`
+* **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
-  [notes](notes.md).
+  the [notes]({{ site.baseurl }}/notes).
 
 * **Nomarkdown override**
-   
-    *Format:* `nomarkdown: (true|false)`
 
-    *Example:* `nomarkdown: false`
+  _Format:_ `nomarkdown: (true|false)`
 
-    *Default:* `nil`
+  _Example:_ `nomarkdown: false`
 
-  Hard setting for `{::nomarkdown}` tags, overrides both autodetection and the global setting in
-  `_config.yml`. See [notes](notes.md) for a detailed explanation. 
+  _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.