jekyll_picture_tag 1.10.0 → 1.13.0

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.

data/docs/usage.md

@@ -1,143 +0,0 @@
----
----
-
-# How to use the Liquid Tag:
-
-## Format:
-
-{% raw %}
-`{% picture [preset] (image) [crop] [alternate images & crops] [attributes] %}`
-{% endraw %}
-
-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 1:1 --alt Example Image %}`
-
-`{% picture example.jpg 16:9 north --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 16:9 east
-  tablet: example_cropped.jpg 3:2 east
-  mobile: example_cropped_more.jpg 1:1-50+0 east
-  --alt Happy Puppy
-  --picture class="hero"
-  --link /
-%}
-```
-
-{% endraw %}
-
-## Argument reference
-
-Given in order:
-
-- **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.
-
-- **Base Image** (Required)
-
-  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.
-
-  For filenames with spaces, either use double quotes (`"my image.jpg"`) or a backslash (`my\ image.jpg`).
-
-- **Crop**
-
-  **Check the [ installation guide ](installation) before using this feature.**
-
-  Crop an image to a given aspect ratio or size. This argument is given as a `geometry` and
-  (optionally) a `gravity`, which can appear in either order and are thin wrappers around
-  ImageMagick's [geometry](http://www.imagemagick.org/script/command-line-processing.php#geometry)
-  and [gravity](http://www.imagemagick.org/script/command-line-options.php#gravity) settings. The
-  values given here will override the preset settings (if present), can be given after every image,
-  and apply only to the preceding image.
-
-  Geometry can take many forms, but most likely you'll want to set an aspect ratio-- given in the
-  standard `width:height` ratio such as `3:2`. Gravity sets which portion of the image to keep, and
-  is given in compass directions (`north`, `southeast`, etc) or `center` (default). Cropping happens
-  before resizing; the preset `widths` setting is a post-crop value.
-
-  If you'd like more fine-grained control, this can be offset by appending `+|-x` and (optionally)
-  `y` pixel values to the _geometry_ (not the gravity!). Example: `1:1+400 west` means "Crop to a
-  1:1 aspect ratio, starting 400 pixels from the left side.", and `north 3:2+0+100` means "Crop to
-  3:2, starting 100 pixels from the top." These can get a bit persnickety; there's nothing to stop
-  you from running off the side of the image. Pay attention.
-
-  For detailed documentation, see ImageMagick's
-  [crop](http://www.imagemagick.org/script/command-line-options.php#crop) tool.
-
-  _Note:_ If you do a lot of trial and error with these, it's a good idea to manually delete your
-  generated images folder more often as each change will build a new set of images without removing
-  the old ones.
-
-- **Alternate images**
-
-  _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 [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 an applicable
-  media query.
-
-- **Attributes**
-
-  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`**
-
-    _Format:_ `--link (some url)`
-
-    _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.
-
-    **Note**: If you get either mangled HTML or extra {::nomarkdown} tags when using this, read
-    [here]({{ site.baseurl }}/notes).
-
-  - **`--alt`**
-
-    _Format:_ `--alt (alt text)`
-
-    _Example:_ `--alt Here is my alt text!`
-
-    Convenience shortcut for `--img alt="..."`
-
-  - **`--(element)`**
-
-    _Format:_ `--(picture|img|source|a|parent) (Standard HTML attributes)`
-
-    _Example:_ `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
-
-    Apply attributes to a given HTML element. Your options are:
-
-    - `picture`
-    - `img`
-    - `source`
-    - `a` (anchor tag)
-    - `parent`
-
-    `--parent` will be applied to the `<picture>` if present, otherwise the `<img>`; useful when
-    using an `auto` output format.