jekyll_picture_tag 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 938a170ac5a3ee774c6d8b95ac2a34e20a1edad04937acf49c7e7bdd081f3b81
-  data.tar.gz: 1648ce3bdf88de7acf55c17d675bfab1ce641cf00a1138b3cf32abafc4824e96
+  metadata.gz: 02cc9448af17bd0cb2811b4f60beb90bea2b95803b694dae29b5606ea39d9a2a
+  data.tar.gz: 58025b92dfeed1607d235cc1ce72195a6f48d722bdf092f8366ab46f7aca74dc
 SHA512:
-  metadata.gz: ce995d57c31dd2beb97c13288a05cca94eaa2ce242e30bcfaf643154dbeec099ce5fa14566b54bd8fc14b21cf8f9da86028fa583f71ad965f368b9db46930ecf
-  data.tar.gz: 105c64ae46f7a5a92c7a198c3ae48e6d49d16493e619107afd0d7c473f577bde43c3baebdfda0692e927fe915f1743dd86ffe8aad7b09c0b48b6b50136625844
+  metadata.gz: 57ae73af226946c529009c7b6af37acaf79596c44e25526ab080b4076c9f1308a09ae694ec4b17eab0c36fa2d92b9f1ab7885188590c63152984cc06cb9bcb60
+  data.tar.gz: be56299cc614da19121ed1e41a1f815b448092804f1813f4e5bb93997628dba0056e02c84ce566dda77ce0fc0feb2aa5a39f467bce70119fbf9f2215f9a6a026

data/.rubocop.yml

@@ -0,0 +1,2 @@
+Style/FrozenStringLiteralComment:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+cache: bundler
+
+before_install:
+  - sudo apt-get install -y webp
+  - gem update --system
+  - gem install bundler
+
+script:
+  - bundle exec rake test
+  - bundle exec rake rubocop

data/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in jekyll-picture-tag.gemspec
-gemspec
+# Specify your gem's dependencies in jekyll_picture_tag.gemspec
+gemspec name: 'jekyll_picture_tag'

data/Rakefile

@@ -3,3 +3,31 @@
 
 require 'bundler/gem_helper'
 Bundler::GemHelper.install_tasks name: 'jekyll_picture_tag'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+# Run all tests
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/test_*.rb']
+end
+
+# Run only unit tests
+Rake::TestTask.new(:unit) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/unit/**/test_*.rb']
+end
+
+# Run only integration tests
+Rake::TestTask.new(:integration) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/integration/**/test_*.rb']
+end
+
+RuboCop::RakeTask.new
+
+# Runs all tests and rubocop
+task default: %i[test rubocop]

data/contributing.md

@@ -0,0 +1,67 @@
+# Contributing
+
+Bug reports, feature requests, and feedback are very welcome, either through github issues or via
+email: robert@buchberger.cc 
+
+Pull requests are encouraged! I'm happy to answer questions and provide assistance along the way.
+Don't let any of the recommendations/requests in this guide stop you from submitting one.
+
+## Setup
+
+Getting up and running is pretty standard-- `git clone`, `cd` into the directory and `bundle
+install`.
+
+## Testing
+
+`rake test` runs the test suite (both unit tests and integration tests). Ignore the mini_magick
+`method redefined` warnings (unless you know how to fix them?) 
+
+`rake unit` runs just the unit tests, while `rake integration` runs the integration tests. The unit
+test coverage isn't stellar, but both unit and integration tests together hit 100%.
+
+Speaking of coverage, simplecov is set up -- you'll get a measurement of coverage in the test output
+and a nice report in the `coverage` directory. I'd like to move to mutation based coverage testing,
+but that's a project for another day.
+
+The tests do output a few images to the `/tmp/` directory, which I'm pretty sure means it won't work
+on Windows. This is fixable if there is a need, so if that gets in your way just ask.
+
+`rake rubocop` checks code formatting, `rake rubocop:auto_correct` will try to fix any rubocop
+issues, if possible.
+
+`rake` will run all tests and rubocop.
+
+## Guidelines
+
+* Generally, go for straightforward and readable rather than terse and clever.
+  I'm not actually a very good programmer; I need simple code that's easy to understand.
+
+* Internal refactoring is welcome, especially in the name of the previous point.
+
+* I'm very reluctant to introduce breaking changes to configuration settings.
+  This rule isn't hard and fast, but I'm not going to do it without a good reason.
+
+* The addition of new test cases whenever relevant is certainly appreciated.
+  This project went for awhile without any proper tests, but now that we're at 100% coverage it
+  would be nice to keep it that way. 
+
+* I've been using 80 characters for code and 100 characters for documentation.
+
+* The code coverage is currently at 100%. I'm not going to make maintaining this a hard and fast
+  rule, but I'd really like to see it stay this way.
+
+## Hard rules
+
+* Liquid tag syntax can only be extended; no breaking changes. I'm not willing to force
+  users to dig through their entire site and change every picture tag in order to update to the
+  latest version.
+
+* Maintain "no configuration required" - a new user must be able to add jpt to their gemfile, bundle
+  install, and start writing picture tags in their site without touching a yml file.
+
+* All tests pass, and all rubocop warnings are addressed.
+
+### Thanks!
+
+As I said, don't let any of the rules & guidelines scare you away. They're the rules for merging
+into master, not submitting a pull request. I'm thrilled to receive any help at all.

data/docs/examples/_config.yml

@@ -0,0 +1,10 @@
+# Sample Jekyll Picture Tag settings
+# Note that all of these settings have sensible defaults. Don't just copy-paste
+# this into your _config.yml!
+picture:
+  source: assets/images/_fullsize
+  output: generated 
+  suppress_warnings: false
+  ignore_missing_images: [development, test]
+  cdn_url: cdn.example.com
+  cdn_environments: production

data/{examples → docs/examples}/_data/picture.yml

@@ -1,7 +1,9 @@
-# Example picture presets:
-# TODO: change to EMs, because safari sucks.
+# These are example settings. I mostly made them up off the top of my head. You
+# probably don't want to just copy-paste these settings. It's worth your time to
+# learn responsive images, so you'll understand what these settings mean.
+# The full documentation for these settings can be found in docs/presets.md
 
-# Media presets are used in several places:
+# 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.
@@ -15,13 +17,14 @@ media_presets:
 # 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:
+  # If you don't specify a preset in the liquid tag (just say 
+  # {% picture image.jpg %}), you'll get the 'default' preset:
   default:
-
-    # Optionally specify a markup type. Your current options are 'picture', 'img', or 'auto'
-    # (default).
+    # What form the output markup should take.
     markup: auto
 
-    # Must be an array, in order of decreasing preference. Defaults to just 'original'.
+    # 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
@@ -30,38 +33,48 @@ markup_presets:
 
     # 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 1800 pixel wide image that's only shown on narrow screens.
+    # 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]
 
-    # 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
-
     # 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
-      desktop: 60vw
+      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
 
-    # Attributes can be added to each HTML element, by type:
+    # 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 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, but you'd like to supply higher resolution images
-  # to devices with higher pixel ratios.
+    # 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
+    base_width: 20 # How wide the 1x image should be
     pixel_ratios: [1, 1.5, 2]
     fallback_width: 20
     attributes:
@@ -71,10 +84,12 @@ markup_presets:
   # 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 # Default: false
+    noscript: true # add a fallback image inside a <noscript> tag.
     attributes: 
       img: class="lazy"
 
@@ -83,3 +98,8 @@ markup_presets:
     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/examples/post.md

@@ -0,0 +1,46 @@
+```
+---
+layout: post
+title: Tag examples
+image: img.jpg
+---
+```
+
+- Standard image, default preset, with alt text:
+
+  `{% picture portrait.jpg --alt An unsual picture %}`
+
+- Select the `gallery` `markup_preset` (which you must define!):
+
+  `{% picture gallery portrait.jpg %} `
+
+- Specify html attributes:
+
+  `{% picture portrait.jpg --picture class="some classes" data-downloadable="true" %}`
+
+- Provide multiple source images for different screen sizes: (note that you must
+define the mobile `media_preset`):
+
+  `{% picture portrait.jpg mobile: portrait-cropped.jpg %}`
+
+- Wrap picture in a link to something: 
+
+  `{% picture portrait.jpg --link /profile.html %}`
+
+- Use liquid variables:
+
+  `{% picture {{ post.image }} %}`
+
+- Line breaks and indentation are fine:
+
+```
+  {% 
+    picture 
+      gallery
+      portrait.jpg
+      mobile: portrait-cropped.jpg
+      --picture class="portrait" data-downloadable="true"
+      --img data-awesomeness="11"
+      --alt Ugly Mug
+  %}
+```

data/docs/global_configuration.md

@@ -0,0 +1,115 @@
+# 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.
+
+  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
+  `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 [this wiki page](https://github.com/rbuchberger/jekyll_picture_tag/wiki/Extra-%7B::nomarkdown%7D-tags-or-mangled-html%3F) for more detailed information. 

data/docs/installation.md

@@ -0,0 +1,30 @@
+# Installation
+
+1. Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group:
+
+```ruby
+group :jekyll_plugins do
+  gem 'jekyll_picture_tag'
+end
+```
+
+2. `bundle install`
+
+3. Verify you have ImageMagick (Good chance you do) by entering the following into a terminal:
+
+```
+$ convert --version
+```
+You should see something like this:
+
+    chronos@localhost ~ $ 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
+
+**Note webp under delegates.** This is required if you want to generate webp files.
+
+If you get a 'command not found' error, you'll need to install it. Most package managers
+know about it, otherwise it can be downloaded [here](https://imagemagick.org/script/download.php).