jekyll_picture_tag 1.10.0 → 1.13.0

data/docs/example_presets.md

@@ -1,116 +0,0 @@
----
----
-# /_data/picture.yml
-
-These are example settings- I mostly made them up off the top of my head. You
-probably don't want to just copy-paste them. The full documentation
-for these can be found [here]({{ site.baseurl }}/presets).
-
-```yml
-
-# Media presets are just named css media queries, used in several places:
-# - To specify alternate source images (for art direction)
-# - To build the 'sizes' attribute
-# - When given alternate source images, specify which sizes to generate.
-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 allow you to group settings together, and select one of them by
-# name in your jekyll tag. All settings are optional.
-markup_presets:
-
-  default:
-    # What form the output markup should take:
-    markup: auto
-
-    # Must be an array, and order matters. Defaults to just 'original', which
-    # does what you'd expect.
-    formats: [webp, original]
-
-    # Must be an array: which image sizes (width in pixels) to generate (unless
-    # directed otherwise below). If not specified, will use sensible default
-    # values.
-    widths: [200, 400, 800, 1600]
-
-    # Alternate source images (for art direction) are associated with media
-    # query presets. Here, you can optionally specify a different set of sizes
-    # to generate for those alternate source images.  This is how you avoid
-    # generating a 1600 pixel wide image that's only shown on narrow screens.
-    # Must be arrays.
-    media_widths: 
-      mobile: [200, 400, 600] 
-      tablet: [400, 600, 800]
-
-    # For building the 'sizes' attribute on img and source tags. specifies how
-    # wide the image will be when a given media query is true. Note that every
-    # source in a given <picture> tag will have the same associated sizes
-    # attribute.
-    sizes: 
-      mobile: 100vw
-      tablet: 80vw
-
-    # Specifies an optional, unconditional size attribute. Can be given alone,
-    # or if specified in combination with 'sizes' below, will be given last
-    # (when no media queries apply).
-    size: 800px
-
-    # Specify the properties of the fallback image. If not specified, will
-    # return a 900 pixel wide image in the original format.
-    fallback_width: 800
-    fallback_format: original
-
-    # Add HTML attributes. 'parent' will go to the <picture> tag if it's there,
-    # otherwise the 'img' tag.
-    attributes:
-      parent: 'data-downloadable="true"'
-      picture: 'class="awesome" data-volume="11"'
-      img: 'class="some-other-class"'
-      a: 'class="image-link"'
-
-    # This will wrap images in a link to the original source image. Obviously
-    # your source images will need to be part of the deployed site for this to
-    # work. If you have issues such as mangled HTML or extra {::nomarkdown}
-    # tags floating around, see docs/notes.md
-    link_source: true
-
-  # This is an example of how you would create a 'multiplier' based srcset;
-  # useful when an image will always be the same size on all screens (icons,
-  # graphics, thumbnails, etc), but you'd like to supply higher resolution
-  # images to devices with higher pixel ratios.
-  icon:
-    base_width: 20 # How wide the 1x image should be
-    pixel_ratios: [1, 1.5, 2]
-    fallback_width: 20
-    attributes:
-      img: 'class="icon"'
-
-  # Here's an example of how you'd configure jekyll-picture-tag to work with
-  # something like lazyload:
-  # https://github.com/verlok/lazyload
-  lazy:
-    # data_auto gives you data-src, data-srcset, and data-sizes instead of src,
-    # srcset, and sizes:
-    markup: data_auto
-    formats: [webp, original]
-    widths: [200, 400, 600, 800]
-    noscript: true # add a fallback image inside a <noscript> tag.
-    attributes: 
-      img: class="lazy"
-
-  # This is an example of how you'd get generated image and a URL, and nothing
-  # else.
-  direct:
-    markup: direct_url
-    fallback_format: webp # Default original
-    fallback_width: 600 # Default 800
-
-  # Here's a naked srcset. Doesn't even give you the surrounding quotes.
-  srcset:
-    markup: naked_srcset
-    formats: [webp] # must be an array, even if it only has one item
-
-```

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. Convenienly 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.