├── .envrc ├── .github └── workflows │ └── code-checks.yml ├── .gitignore ├── .rubocop.yml ├── .ruby-version ├── .solargraph.yml ├── Gemfile ├── LICENSE.txt ├── Rakefile ├── docs ├── .envrc ├── Gemfile ├── Gemfile.lock ├── _config.yml ├── devs │ ├── contributing │ │ ├── code.md │ │ ├── docs.md │ │ ├── index.md │ │ ├── setup.md │ │ └── testing.md │ ├── index.md │ └── releases.md ├── index.md ├── logo.png └── users │ ├── configuration │ ├── directories.md │ ├── disable.md │ ├── fast_build.md │ ├── ignore_missing.md │ ├── index.md │ ├── kramdown_fix.md │ ├── suppress_warnings.md │ └── urls.md │ ├── deployment.md │ ├── getting_started.md │ ├── index.md │ ├── installation.md │ ├── liquid_tag │ ├── argument_reference │ │ ├── alternate_images.md │ │ ├── attributes.md │ │ ├── base_image.md │ │ ├── crop.md │ │ ├── link.md │ │ ├── preset.md │ │ └── readme.md │ ├── examples.md │ └── index.md │ ├── notes │ ├── git_lfs.md │ ├── html_attributes.md │ ├── index.md │ ├── kramdown_bug.md │ ├── managing_images.md │ ├── migration_1.md │ └── migration_2.md │ ├── presets │ ├── cropping.md │ ├── default.md │ ├── examples.md │ ├── fallback_image.md │ ├── html_attributes.md │ ├── image_formats.md │ ├── image_quality.md │ ├── index.md │ ├── link_source.md │ ├── markup_formats │ │ ├── fragments.md │ │ ├── javascript_friendly.md │ │ ├── readme.md │ │ └── standard_html.md │ ├── media_queries.md │ ├── nomarkdown_override.md │ ├── pixel_ratio_srcsets.md │ ├── quality_width_graph.png │ ├── subpresets.md │ ├── width_height_attributes.md │ ├── width_srcsets.md │ └── writing_presets.md │ └── tutorial.md ├── jekyll_picture_tag.gemspec ├── lib ├── jekyll_picture_tag.rb └── jekyll_picture_tag │ ├── cache.rb │ ├── defaults │ ├── global.rb │ └── presets.rb │ ├── images.rb │ ├── images │ ├── generated_image.rb │ ├── image_file.rb │ ├── img_uri.rb │ └── source_image.rb │ ├── instructions.rb │ ├── instructions │ ├── children │ │ ├── config.rb │ │ ├── context.rb │ │ ├── params.rb │ │ ├── parsers.rb │ │ └── preset.rb │ └── parents │ │ ├── conditional_instruction.rb │ │ └── env_instruction.rb │ ├── output_formats.rb │ ├── output_formats │ ├── auto.rb │ ├── basic.rb │ ├── data_attributes.rb │ ├── data_auto.rb │ ├── data_img.rb │ ├── data_picture.rb │ ├── direct_url.rb │ ├── img.rb │ ├── naked_srcset.rb │ ├── picture.rb │ └── readme.md │ ├── parsers.rb │ ├── parsers │ ├── arg_splitter.rb │ ├── configuration.rb │ ├── html_attributes.rb │ ├── image_backend.rb │ ├── preset.rb │ └── tag_parser.rb │ ├── router.rb │ ├── srcsets.rb │ ├── srcsets │ ├── basic.rb │ ├── pixel_ratio.rb │ └── width.rb │ ├── utils.rb │ └── version.rb ├── package-lock.json ├── readme.md └── test ├── .rubocop.yml ├── .solargraph.yml ├── image_files ├── pestka.jpg ├── pestka_transparent.png ├── rms with space.jpg ├── rms.avif ├── rms.gif ├── rms.jp2 ├── rms.jpg ├── rms.png ├── rms.webp └── spx.jpg ├── integration ├── integration_test_helper.rb ├── readme.md ├── test_config.rb ├── test_params.rb ├── test_presets.rb └── test_validation.rb ├── stubs.rb ├── stubs ├── instructions.rb ├── jekyll.rb ├── presets.rb └── structs.rb ├── test_helper.rb └── unit ├── images ├── test_generated_image.rb ├── test_generated_image_missing.rb ├── test_image_file.rb ├── test_img_uri.rb ├── test_source_image.rb └── test_source_image_missing.rb ├── instructions └── test_instructions.rb ├── output_formats ├── output_format_test_helper.rb ├── test_auto.rb ├── test_data_auto.rb ├── test_data_img.rb ├── test_data_picture.rb ├── test_direct_url.rb ├── test_img.rb ├── test_naked_srcset.rb └── test_picture.rb ├── parsers ├── test_backend.rb └── test_tag_parser.rb ├── srcsets ├── srcsets_test_helper.rb ├── test_pixel_ratio.rb └── test_width.rb ├── test_cache.rb ├── test_router.rb └── test_utils.rb /.envrc: -------------------------------------------------------------------------------- 1 | # if you run bundle install --binstubs, you won't have to use bundle exec all the time. 2 | export PATH=$(git rev-parse --show-toplevel)/bin:$PATH 3 | # Suppress a few vips warnings that pop up during the tests 4 | export VIPS_WARNING=0 5 | -------------------------------------------------------------------------------- /.github/workflows/code-checks.yml: -------------------------------------------------------------------------------- 1 | name: 'Tests & Formatting' 2 | 3 | on: 4 | push: 5 | branches: [master] 6 | pull_request: 7 | branches: [master] 8 | 9 | jobs: 10 | checks: 11 | runs-on: ubuntu-20.04 12 | 13 | steps: 14 | 15 | - name: Install system dependencies 16 | run: sudo apt install libjpeg-dev webp libpng-dev libavifile-0.7c2 libopenjpip7 imagemagick libvips-tools 17 | 18 | - name: Checkout repo 19 | uses: actions/checkout@v2 20 | 21 | # Version taken from .ruby-version file. 22 | # Also runs bundle install. 23 | - name: Install Ruby 24 | uses: ruby/setup-ruby@v1 25 | with: 26 | bundler-cache: true 27 | 28 | - run: bundle exec rake test 29 | 30 | - run: bundle exec rubocop 31 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /.bundle/ 2 | /docs/.bundle/ 3 | /.yardoc 4 | /Gemfile.lock 5 | /_yardoc/ 6 | /coverage/ 7 | /doc/ 8 | /pkg/ 9 | /spec/reports/ 10 | /tmp/ 11 | .idea 12 | jekyll-picture-tag.iml 13 | *.gem 14 | /docs/_site/ 15 | /docs/.jekyll-cache/ 16 | /docs/.sass-cache/ 17 | /bin/ 18 | /docs/bin/ 19 | -------------------------------------------------------------------------------- /.rubocop.yml: -------------------------------------------------------------------------------- 1 | # Exclude unimportant files 2 | require: 3 | - rubocop-minitest 4 | - rubocop-rake 5 | 6 | AllCops: 7 | NewCops: enable 8 | Include: 9 | - 'lib/**/*.rb' 10 | - 'test/**/*.rb' 11 | - 'Gemfile' 12 | - 'Rakefile' 13 | - '*.gemspec' 14 | 15 | Exclude: 16 | - '**/.bundle/*' 17 | - '**/.git/*' 18 | - '**/.github/*' 19 | - '**/bin/**/*' 20 | - '**/coverage/**/*' 21 | - '**/docs/**/*' 22 | - '**/imagemagick/*' 23 | - '**/pkg/**/*' 24 | - '**/vendor/**/*' 25 | 26 | Layout/LineLength: 27 | Max: 120 28 | 29 | # Disabled Cops 30 | Style/FrozenStringLiteralComment: 31 | Enabled: false 32 | 33 | Style/StringConcatenation: 34 | Enabled: false 35 | 36 | Metrics/MethodLength: 37 | Enabled: false 38 | -------------------------------------------------------------------------------- /.ruby-version: -------------------------------------------------------------------------------- 1 | 2.6.6 2 | -------------------------------------------------------------------------------- /.solargraph.yml: -------------------------------------------------------------------------------- 1 | --- 2 | include: 3 | - "**/*.rb" 4 | - "**/*.gemspec" 5 | exclude: 6 | - spec/**/* 7 | - test/**/* 8 | - vendor/**/* 9 | - ".bundle/**/*" 10 | require: [] 11 | domains: [] 12 | reporters: 13 | - rubocop 14 | require_paths: [] 15 | max_files: 5000 16 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | 3 | # Specify your gem's dependencies in jekyll_picture_tag.gemspec 4 | gemspec name: 'jekyll_picture_tag' 5 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Copyright (c) 2013, Robert Wierzbowski 2 | All rights reserved. 3 | 4 | Redistribution and use in source and binary forms, with or without 5 | modification, are permitted provided that the following conditions are met: 6 | * Redistributions of source code must retain the above copyright 7 | notice, this list of conditions and the following disclaimer. 8 | * Redistributions in binary form must reproduce the above copyright 9 | notice, this list of conditions and the following disclaimer in the 10 | documentation and/or other materials provided with the distribution. 11 | * Neither the name of the nor the 12 | names of its contributors may be used to endorse or promote products 13 | derived from this software without specific prior written permission. 14 | 15 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 16 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18 | DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY 19 | DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 22 | ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 24 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -------------------------------------------------------------------------------- /Rakefile: -------------------------------------------------------------------------------- 1 | # Since we have two gemfiles, we can't just require 'bundler/gem_tasks'. We have 2 | # to explicitly set its name and install them: 3 | 4 | require 'bundler/gem_helper' 5 | Bundler::GemHelper.install_tasks name: 'jekyll_picture_tag' 6 | require 'rake/testtask' 7 | require 'rubocop/rake_task' 8 | 9 | # Run all tests 10 | Rake::TestTask.new(:test) do |t| 11 | t.libs << 'test' 12 | t.libs << 'lib' 13 | t.test_files = FileList['test/**/test_*.rb'] 14 | end 15 | 16 | # Run only unit tests 17 | Rake::TestTask.new(:unit) do |t| 18 | t.libs << 'test' 19 | t.libs << 'lib' 20 | t.test_files = FileList['test/unit/**/test_*.rb'] 21 | end 22 | 23 | # Run only integration tests 24 | Rake::TestTask.new(:integration) do |t| 25 | t.libs << 'test' 26 | t.libs << 'lib' 27 | t.test_files = FileList['test/integration/**/test_*.rb'] 28 | end 29 | 30 | RuboCop::RakeTask.new 31 | 32 | # Runs all tests and rubocop 33 | task default: %i[test rubocop] 34 | -------------------------------------------------------------------------------- /docs/.envrc: -------------------------------------------------------------------------------- 1 | # if you run bundle install --binstubs, you won't have to use bundle exec all the time. 2 | export PATH=$(git rev-parse --show-toplevel)/docs/bin:$PATH 3 | -------------------------------------------------------------------------------- /docs/Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | 3 | group :jekyll_plugins do 4 | gem 'github-pages' 5 | end 6 | -------------------------------------------------------------------------------- /docs/_config.yml: -------------------------------------------------------------------------------- 1 | remote_theme: rbuchberger/jekyll-rtd-theme@main 2 | 3 | title: Jekyll Picture Tag 4 | description: Images for Jekyll, done correctly. 5 | lang: en-US 6 | 7 | baseurl: '/jekyll_picture_tag' 8 | readme_index: 9 | with_frontmatter: true 10 | -------------------------------------------------------------------------------- /docs/devs/contributing/code.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 4 3 | --- 4 | 5 | # Code 6 | 7 | ## Commit guidelines 8 | 9 | * The commit log should be a history of small, coherent changes. Commits are cheap, make no attempt 10 | to minimize the number of them! Yes, it's messy. Yes it makes the commit log longer. It's also far 11 | more useful than a nice, tidy, one-commit-per-pull-request log. 12 | 13 | * Follow the existing commit message style. Start with a capitalized, present tense verb and say 14 | what the commit does. If the reason why isn't obvious, explain in the extended message. 15 | 16 | ## Code Guidelines 17 | 18 | * Generally, go for straightforward and readable rather than terse and clever. I'm not actually a 19 | very good programmer; I need simple code that's easy to understand. 20 | 21 | * Refactoring is welcome, especially in the name of the previous point. 22 | 23 | * I'm very reluctant to introduce breaking changes to configuration settings. This rule isn't 24 | absolute, but I'm not going to do it without a good reason. 25 | 26 | * Don't disable cops without strong justification. 27 | 28 | * I generally try to write tests before writing code, especially when fixing bugs. This 29 | gives us some confidence that what we think we're testing and what we're actually testing aren't 30 | too different. 31 | 32 | ## Hard rules 33 | 34 | These aren't the rules for submitting a pull request, these are the rules for merging into master. 35 | I'm thrilled to receive any help at all, and I'm more than happy to help with meeting these 36 | criteria: 37 | 38 | * Liquid tag syntax can only be extended; no breaking changes. I'm not willing to force 39 | users to dig through their entire site and change every picture tag in order to update to the 40 | latest version. 41 | 42 | * Maintain "no configuration required" - a new user must be able to add JPT to their gemfile, bundle 43 | install, and start writing picture tags in their site without touching a yml file. 44 | 45 | * Good test coverage, > 90%. Not every line must be tested, but every line that matters should be. 46 | 47 | * No failing tests 48 | 49 | * No rubocop warnings 50 | 51 | ## Thanks! 52 | 53 | As I said, don't let any of the rules & guidelines scare you away. They're the rules for merging 54 | into master, not submitting a pull request. I'm thrilled to receive any help at all. 55 | -------------------------------------------------------------------------------- /docs/devs/contributing/docs.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 2 3 | --- 4 | 5 | # Docs 6 | 7 | The docs are a mini-project in the docs folder. They don't have a dedicated git repository, but they 8 | do have their own Gemfile. They run on Github Pages, which is based on Jekyll. 9 | 10 | The format is simple; markdown files with a few lines of metadata at the top, organized into 11 | subdirectories. We're using the [jekyll-rtd-theme](https://jekyll-rtd-theme.rundocs.io/). 12 | 13 | You can preview as you edit; first the setup: 14 | 15 | ``` sh 16 | $ git clone https://github.com/rbuchberger/jekyll_picture_tag.git # if you haven't already 17 | $ cd jekyll_picture_tag/docs 18 | $ direnv allow # (optional) 19 | $ bundle install --binstubs # --binstubs is optional. 20 | ``` 21 | 22 | If you use direnv or add `docs/bin` to your `PATH` another way, the `--binstubs` flag allows you to 23 | skip `bundle exec`. 24 | 25 | To preview: 26 | 27 | ``` sh 28 | $ jekyll serve --livereload # (prefix with `bundle exec` if necessary) 29 | ``` 30 | 31 | * In a web browser, navigate to `localhost:4000/jekyll_picture_tag/` 32 | -------------------------------------------------------------------------------- /docs/devs/contributing/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | --- 3 | # Contributing 4 | 5 | Bug reports, feature requests, and feedback are very welcome, either through 6 | github issues or via email: robert@buchberger.cc 7 | 8 | Pull requests are encouraged! I'm happy to answer questions and provide 9 | assistance along the way. Don't let any of the recommendations/requests in this 10 | guide stop you from submitting one. 11 | 12 | I think one of the biggest opportunities for improvement in this plugin is its 13 | documentation. I'd really love help here, and all you need to know is markdown. 14 | 15 | {% include list.liquid %} 16 | -------------------------------------------------------------------------------- /docs/devs/contributing/setup.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 1 3 | --- 4 | 5 | ## Setup 6 | 7 | I use [asdf](https://github.com/asdf-vm/asdf) and [direnv](https://direnv.net/) (via 8 | [asdf-direnv](https://github.com/asdf-community/asdf-direnv)). They add convenience, but they aren't 9 | required by any means. 10 | 11 | ### With asdf & direnv: 12 | 13 | ```sh 14 | $ git clone https://github.com/rbuchberger/jekyll_picture_tag.git 15 | $ cd jekyll_picture_tag 16 | $ direnv allow 17 | $ asdf install 18 | $ bundle install --binstubs 19 | ``` 20 | 21 | ### Without asdf & direnv 22 | 23 | ```sh 24 | $ git clone https://github.com/rbuchberger/jekyll_picture_tag.git 25 | $ cd jekyll_picture_tag 26 | # Install the correct version of ruby, with the bundler gem. 27 | $ bundle install 28 | ``` 29 | 30 | * The currently targeted ruby version can be found in the `.ruby-version` file in the project root; 31 | ensure your version manager of choice knows about it. 32 | * If you add the project's `bin/` folder to your path, and run `bundle install --binstubs`, you won't 33 | have to use `bundle exec` for `rake` commands and such. 34 | -------------------------------------------------------------------------------- /docs/devs/contributing/testing.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 3 3 | --- 4 | 5 | # Tests 6 | 7 | The primary way to run these checks is `rake`: 8 | 9 | | rake command | function | 10 | |-----------------------------|---------------------------------| 11 | | `rake unit` | Unit tests only | 12 | | `rake integration` | Integration tests only | 13 | | `rake test` | Both unit and integration tests | 14 | | `rake rubocop` | Check code formatting | 15 | | `rake rubocop:auto_correct` | Fix rubocop issues, if possible | 16 | | `rake` | Run all checks | 17 | 18 | * Ignore the mini_magick `method redefined` warnings (unless you know how to fix them?) 19 | * Depending on your environment, you may need to prefix all rake commands with `bundle exec` 20 | * Simplecov is set up -- you'll get a measurement of coverage in the test output and a nice report 21 | in the `coverage` directory. 22 | * The tests use the `/tmp/` directory directly, which I'm pretty sure means it won't work on 23 | Windows. This is fixable, so if that gets in your way just ask. 24 | -------------------------------------------------------------------------------- /docs/devs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 2 3 | --- 4 | 5 | # Development 6 | 7 | {% include list.liquid %} 8 | -------------------------------------------------------------------------------- /docs/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rbuchberger/jekyll_picture_tag/a0efa5c15a1e838540f61d363e1de492fc554d75/docs/logo.png -------------------------------------------------------------------------------- /docs/users/configuration/directories.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 1 3 | --- 4 | 5 | # Directories 6 | 7 | Define where JPT should look for source images, and where it should place 8 | generated images. 9 | 10 | ## Source 11 | 12 | *Format:* `source: (directory)` 13 | 14 | *Example:* `source: images/` 15 | 16 | *Default:* Jekyll site root. 17 | 18 | Base directory for your source images, relative to the Jekyll site root. For 19 | example, if set to `images/_fullsize`: 20 | 21 | this tag: {% raw %} `{% picture enishte/portrait.jpg %}` {% endraw %} 22 | will use this path: `images/_fullsize/enishte/portrait.jpg`. 23 | 24 | ## Output 25 | 26 | *Format:* `output: (directory)` 27 | 28 | *Example:* `output: resized_images/` 29 | 30 | *Default*: `generated/` 31 | 32 | Save resized, reformatted images to this directory in your compiled site. The 33 | `source` directory structure is maintained. Relative to your compiled site 34 | directory, which means `_site/` unless you've changed it. 35 | -------------------------------------------------------------------------------- /docs/users/configuration/disable.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 5 3 | --- 4 | 5 | # Disable Jekyll Picture Tag 6 | 7 | *Format:* `disabled: (true|false|environment|array of environments)` 8 | 9 | *Examples:* 10 | 11 | - `disabled: true` 12 | 13 | - `disabled: development` 14 | 15 | - `disabled: [development, staging]` 16 | 17 | *Default:* `false` 18 | 19 | Disable image and markup generation entirely. Useful for debugging, or to speed 20 | up site builds when you're working on something else. 21 | 22 | Hint: If you're going to toggle this frequently, you might use a Jekyll 23 | Environment. Set this to something like `nopics`, and then start Jekyll with 24 | `JEKYLL_ENV=nopics bundle exec jekyll serve`. 25 | -------------------------------------------------------------------------------- /docs/users/configuration/fast_build.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 4 3 | --- 4 | 5 | # Fast Build 6 | 7 | *Format:* `fast_build: (boolean|environment|environments)` 8 | 9 | *Examples:* 10 | 11 | - `fast_build: true` 12 | 13 | - `fast_build: development` 14 | 15 | - `fast_build: [development, staging]` 16 | 17 | *Default:* `false` 18 | 19 | *Might* make your builds faster (depending on hardware and how many images you 20 | have) by making a tradeoff: assuming that the filename alone is enough to 21 | uniquely identify a source image. This doesn't speed up image generation, just 22 | detection of whether or not it's necessary. 23 | 24 | Ordinarily, JPT computes an MD5 hash for every source image, every site build. 25 | This ensures that if you replace one image with another, but keep the filename 26 | the same, JPT will correctly generate images for the new file. Enable this 27 | setting to skip MD5 hash checking and just assume that if the filename, format, 28 | and width match then it's the right one. 29 | -------------------------------------------------------------------------------- /docs/users/configuration/ignore_missing.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 4 3 | --- 4 | 5 | # Ignore Missing Source Images 6 | 7 | *Format:* `ignore_missing_images: (boolean|environment|environments)` 8 | 9 | *Examples:* 10 | - `ignore_missing_images: true` 11 | - `ignore_missing_images: development` 12 | - `ignore_missing_images: [development, testing]` 13 | 14 | *Default:* `false` 15 | 16 | Normally, JPT will raise an error if a source image is missing, causing the 17 | entire site build to fail. This setting allows you to bypass this behavior and 18 | continue the build, either for certain build environments or all the time. 19 | 20 | I highly encourage you to set this to `development`, and set the Jekyll build 21 | environment to `production` when you build for production so you don't shoot 22 | yourself in the foot. You can read more about Jekyll environments 23 | [here](https://jekyllrb.com/docs/configuration/environments/). 24 | -------------------------------------------------------------------------------- /docs/users/configuration/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 1 3 | --- 4 | # Global Configuration 5 | 6 | **All configuration is optional**. If you are happy with the defaults, you don't 7 | have to touch a single yml file. 8 | 9 | Global settings are stored under the `picture:` key in `/_config.yml`. 10 | 11 | **Example:** 12 | 13 | ```yml 14 | # _config.yml 15 | 16 | (...) 17 | 18 | picture: 19 | source: "assets/images/fullsize" 20 | output: "assets/images/generated" 21 | suppress_warnings: true 22 | (...) 23 | 24 | (...) 25 | ``` 26 | 27 | ## Reference 28 | 29 | {% include list.liquid %} 30 | -------------------------------------------------------------------------------- /docs/users/configuration/kramdown_fix.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 6 3 | --- 4 | 5 | # Kramdown Fix 6 | 7 | *Format:* `nomarkdown: (true|false)` 8 | 9 | *Example:* `nomarkdown: false` 10 | 11 | *Default:* `true` 12 | 13 | Whether or not to surround j-p-t's output with a 14 | `{::nomarkdown}..{:/nomarkdown}` block when called from within a markdown file. 15 | When false, JPT will never add the wrapper. When true, JPT will add it only when 16 | it believes it's necessary, though it's not 100% accurate at making this 17 | determination. 18 | 19 | This setting is overridden by the same setting in a preset. See [this note]({{ 20 | site.baseurl }}/users/notes/kramdown_bug) for more detailed information. 21 | -------------------------------------------------------------------------------- /docs/users/configuration/suppress_warnings.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 3 3 | --- 4 | 5 | # Suppress Warnings 6 | 7 | *Format:* `suppress_warnings: (true|false)` 8 | 9 | *Example:* `suppress_warnings: true` 10 | 11 | *Default*: `false` 12 | 13 | Jekyll Picture Tag will warn you in a few different scenarios, such as when your 14 | base image is smaller than one of the sizes in your preset. (Note that Jekyll 15 | Picture Tag will never resize an image to be larger than its source). Set this 16 | value to `true`, and these warnings will not be shown. 17 | -------------------------------------------------------------------------------- /docs/users/configuration/urls.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 2 3 | --- 4 | 5 | # URLs 6 | 7 | ## Relative or Absolute 8 | 9 | *Format:* `relative_url: (true|false)` 10 | 11 | *Example:* `relative_url: false` 12 | 13 | *Default*: `true` 14 | 15 | Whether to use relative (`/generated/test(...).jpg`) or absolute 16 | (`https://example.com/generated/test(...).jpg`) urls in your src and srcset attributes. 17 | 18 | ## Baseurl Key 19 | 20 | *Format:* `baseurl_key: (string)` 21 | 22 | *Example:* `baseurl_key: baseurl_root` 23 | 24 | *Default*: `baseurl` 25 | 26 | Some plugins, such as 27 | [jekyll-multiple-languages-plugin](https://github.com/kurtsson/jekyll-multiple-languages-plugin), 28 | work by modifying the standard `baseurl` setting, which can break JPT's images. It offers a new 29 | setting, `baseurl_root`, which serves as the original `baseurl` setting without a language prefix. 30 | Using `baseurl_key`, you can direct JPT to use that setting instead. 31 | 32 | ## Ignore Baseurl 33 | 34 | *Format:* `ignore_baseurl: (true|false)` 35 | 36 | *Example:* `ignore_baseurl: true` 37 | 38 | *Default*: `false` 39 | 40 | Depending on your other plugins and configuration, it may be useful for JPT to ignore the baseurl 41 | setting entirely. 42 | 43 | ## CDN URL 44 | 45 | Use for images that are hosted at a different domain or subdomain than the Jekyll site root. 46 | Overrides `relative_url`. 47 | 48 | *Format:* `cdn_url: (url)` 49 | 50 | *Example:* `cdn_url: https://cdn.example.com` 51 | 52 | *Default*: none 53 | 54 | ## CDN Environments 55 | 56 | It's likely that if you're using a CDN, you may not want to use it in your local development 57 | environment. This allows you to build a site with local images while in development, and still push 58 | to a CDN when you build for production by specifying a different 59 | [environment](https://jekyllrb.com/docs/configuration/environments/). 60 | 61 | *Format:* `cdn_environments: (array of strings)` 62 | 63 | *Example:* `cdn_environments: ['production', 'staging']` 64 | 65 | *Default*: `['production']` 66 | 67 | **Note that the default jekyll environment is `development`**, meaning that if you only set 68 | `cdn_url` and run `jekyll serve` or `jekyll build`, nothing will change. Either run 69 | `JEKYLL_ENV=production bundle exec jekyll build`, or add `development` to this setting. 70 | -------------------------------------------------------------------------------- /docs/users/getting_started.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 2 3 | --- 4 | 5 | # Getting started 6 | 7 | Firstly, let me warn you that responsive images are somewhat complicated, and fall squarely into 8 | "proper web development" territory. To do this well, you will need to do some learning. The default 9 | settings are a starting point, meant to get you up and running with something reasonable while 10 | minimizing unexpected behavior. 11 | 12 | Here are some good guides: 13 | 14 | * [MDN Responsive Images guide](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) 15 | * [CSS Tricks Guide to Reponsive Images](https://css-tricks.com/a-guide-to-the-responsive-images-syntax-in-html/) 16 | * [Cloud 4 - Responsive Images 101](https://cloudfour.com/thinks/responsive-images-101-definitions/) 17 | 18 | ## Step 1: Customize global settings 19 | 20 | JPT's [global configuration](configuration) happens under the `picture:` key in `_config.yml`. The 21 | defaults are probably fine, though you may want to configure the input and output 22 | [directories](configuration/directories). 23 | 24 | ## Step 2: Test & Learn 25 | 26 | - If you're not already familiar, there's a short [tutorial](tutorial) to get you started with the basics. 27 | - Look over the [example presets](presets/examples) 28 | - Look over the [example liquid tags](liquid_tag/examples) and [instructions](liquid_tag). 29 | 30 | ## Step 3: Add breakpoints 31 | 32 | Once you have a feel for how this plugin works, it's time to adapt it to your particular site. The 33 | built-in `jpt-` media queries probably don't quite fit your layout; Find whatever breakpoints your 34 | css uses, and tell JPT about them: 35 | 36 | 1. Create `_data/picture.yml` 37 | 2. List them under the `media_queries:` key. Give them easy-to-remember names, and wrap them in 38 | single quotes. 39 | 40 | ```yaml 41 | # _data/picture.yml 42 | 43 | media_queries: 44 | (name): '(media query)' 45 | (...) 46 | 47 | ``` 48 | 49 | If you're using bootstrap or something, you don't need to plug in every single breakpoint they have, 50 | just a handful that you'll actually use. 51 | 52 | ## Step 4: Write presets 53 | 54 | From there, it's time to [write your own presets](presets). Start with the `default`, and then move 55 | on to cover all the different ways you use images in your site. 56 | -------------------------------------------------------------------------------- /docs/users/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 1 3 | --- 4 | 5 | # Usage 6 | 7 | {% include list.liquid %} 8 | -------------------------------------------------------------------------------- /docs/users/installation.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 1 3 | --- 4 | 5 | # Installation 6 | 7 | 1. Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group. 8 | 9 | ```note 10 | It's NOT `jekyll-picture-tag`. 11 | ``` 12 | 13 | ```ruby 14 | # Gemfile 15 | 16 | gem 'jekyll', '~> 4.0' 17 | 18 | group :jekyll_plugins do 19 | # (other jekyll plugins) 20 | gem 'jekyll_picture_tag', '~> 2.0' 21 | end 22 | ``` 23 | 24 | 2. Run `$ bundle install` 25 | 3. Install `libvips`. Most package managers know about it, otherwise it can be found 26 | [here](https://libvips.github.io/libvips/install.html). 27 | 4. Install libvips dependencies for all image formats you will use, such as `libpng`, `libwebp`, 28 | `libjpeg`, and `libheif` (for avif). Note that if you use a deployment or CI service, these 29 | dependencies will be required there as well. 30 | 5. Optional: Install `ImageMagick` for additional image formats. If vips runs into an image format 31 | it can't handle (jp2 on my particular installation), JPT will instruct it to try ImageMagick 32 | instead. 33 | -------------------------------------------------------------------------------- /docs/users/liquid_tag/argument_reference/alternate_images.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 4 3 | --- 4 | 5 | # Alternate images 6 | 7 | _Format:_ `(media_query): (filename) [crop] [gravity] (...)` 8 | 9 | _Example:_ `tablet: img_cropped.jpg mobile: img_cropped_more.jpg` 10 | 11 | Optionally specify any number of alternate base images for given 12 | [media_queries]({{ site.baseurl }}/users/presets/media_queries). This is called 13 | [art direction](http://usecases.responsiveimages.org/#art-direction), and is one 14 | of JPT's strongest features. 15 | 16 | Give your images in order of ascending specificity (The first image is the 17 | most general). They will be provided to the browser in reverse order, and it 18 | will select the first one with an applicable media query. 19 | -------------------------------------------------------------------------------- /docs/users/liquid_tag/argument_reference/attributes.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 6 3 | --- 4 | 5 | # Attributes 6 | 7 | Optionally specify any number of HTML attributes. These will be combined with 8 | any which you've set in a preset. 9 | 10 | All arguments which begin with `--` (including `--link`) must be at the end of 11 | the liquid tag, but they can be given in any order. 12 | 13 | - **`--alt`** 14 | 15 | _Format:_ `--alt (alt text)` 16 | 17 | _Example:_ `--alt Here is my alt text!` 18 | 19 | Convenience shortcut for `--img alt="..."` 20 | 21 | - **`--(element)`** 22 | 23 | _Format:_ `--(picture|img|source|a|parent) (Standard HTML attributes)` 24 | 25 | _Example:_ `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"` 26 | 27 | Apply attributes to a given HTML element. Your options are: 28 | 29 | - `--picture` 30 | - `--img` 31 | - `--source` 32 | - `--a` (anchor tag) 33 | - `--parent` 34 | 35 | `--parent` will be applied to the `` if present, otherwise the 36 | ``; useful when using an `auto` output format. 37 | 38 | ```note 39 | Attributes that are set here for elements which don't occur in the selected 40 | markup format will be ignored (e.g. adding `--picture class="cool-css"` with a 41 | preset that does not use a `` tag). 42 | ``` 43 | -------------------------------------------------------------------------------- /docs/users/liquid_tag/argument_reference/base_image.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 2 3 | --- 4 | 5 | # Base Image (Required) 6 | 7 | Can be any raster image (as long as you have the required ImageMagick delegate). 8 | Relative to Jekyll's root directory, or the `source` [setting]({{ site.baseurl 9 | }}/users/configuration/directories) if you've configured it. 10 | 11 | For filenames with spaces, either use double quotes (`"my image.jpg"`) or a 12 | backslash (`my\ image.jpg`). 13 | -------------------------------------------------------------------------------- /docs/users/liquid_tag/argument_reference/crop.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 3 3 | --- 4 | 5 | # Crop 6 | 7 | Crop an image to a given aspect ratio. This argument is given as a `crop` and (optionally) a `keep` 8 | setting. The values given here will override the preset settings (if present), can be given after 9 | every image, and apply only to the preceding image. 10 | 11 | `crop` is given as an aspect ratio in the `width:height` format. 12 | 13 | `keep` sets which portion of the image to keep; it's the 14 | ['interestingness'](https://libvips.github.io/libvips/API/current/libvips-conversion.html#VipsInteresting) 15 | setting passed to the [libvips 16 | smartcrop](https://libvips.github.io/libvips/API/current/libvips-conversion.html#vips-smartcrop) 17 | function. Your options are: 18 | 19 | * `attention` - automagically keep parts likely to draw human attention. **Default** 20 | * `entropy` - Crop out the parts with the least variation. 21 | * `center` or `centre` - Keep the middle part. 22 | 23 | ```note 24 | Cropping happens before resizing; the preset `widths` setting is a post-crop value. 25 | ``` 26 | 27 | More fine-grained control is beyond the scope of this plugin. I'm not writing an image editor here! 28 | 29 | ## Examples 30 | 31 | - `16:9` 32 | - `1:1 entropy` 33 | - `3:2 center` 34 | -------------------------------------------------------------------------------- /docs/users/liquid_tag/argument_reference/link.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 5 3 | --- 4 | 5 | # Link 6 | 7 | _Format:_ `--link (some url)` 8 | 9 | _Examples_: `--link https://example.com`, `--link /blog/some_post/` 10 | 11 | Wrap the image in an anchor tag, with the `href` attribute set to whatever 12 | value you give it. This will override automatic source image linking, if you 13 | have enabled it. 14 | 15 | **Note**: If you get either mangled HTML or extra {::nomarkdown} tags when 16 | using this, read [here]({{ site.baseurl }}/users/notes/kramdown_bug). 17 | -------------------------------------------------------------------------------- /docs/users/liquid_tag/argument_reference/preset.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 1 3 | --- 4 | 5 | # Preset 6 | 7 | Select a [preset]({{ site.baseurl }}/users/presets), or omit to 8 | use the `default` preset. A preset is a collection of settings which determines 9 | nearly everything about JPT's output, from the image formats used to the exact 10 | format your final HTML will take. Think of it like a recipe or a blueprint; JPT 11 | will take the information provided in the liquid tag, combine it with the 12 | settings written in the preset, and use it to craft your images and markup. 13 | 14 | If the `preset` is omitted then default settings will be used, in the simplest 15 | case resulting in an `` tag containing a srcset pointing to your newly 16 | generated images. You are free to override the `default` preset and define 17 | your own settings, giving full flexibility in what JPT will create. 18 | -------------------------------------------------------------------------------- /docs/users/liquid_tag/argument_reference/readme.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 3 3 | --- 4 | 5 | # Argument Reference 6 | 7 | Given in order: 8 | 9 | {% include list.liquid %} 10 | -------------------------------------------------------------------------------- /docs/users/liquid_tag/examples.md: -------------------------------------------------------------------------------- 1 | --- 2 | --- 3 | # Examples 4 | 5 | {% raw %} 6 | 7 | * Basic form, will use the preset named 'default': 8 | ``` 9 | {% picture example.jpg %} 10 | ``` 11 | 12 | * Include alt text: 13 | ``` 14 | {% picture example.jpg --alt Alt Text %} 15 | ``` 16 | 17 | * Select a `preset` (defined in `_data/picture.yml`: 18 | ``` 19 | {% picture my_preset example.jpg %} 20 | ``` 21 | 22 | * Show different images on different devices. (Note that `mobile` must be set 23 | to some media query under `media_queries:` in `_data/picture.yml`. 24 | ``` 25 | {% picture example.jpg mobile: example_cropped.jpg %} 26 | ``` 27 | 28 | * Use liquid variables: 29 | ``` 30 | {% picture "{{ page.some_liquid_variable }}" %} 31 | ``` 32 | 33 | * Select the blog_index preset, use liquid variables, and wrap the image in an 34 | anchor tag (link): 35 | ``` 36 | {% picture blog_index "{{ post.image }}" --link {{ post.url }} %} 37 | ``` 38 | 39 | **Note:** If the image path is coming from a liquid variable then you should guard against spaces 40 | by wrapping the inner tag in quotes, as in the previous examples. 41 | 42 | * Add arbitrary HTML attributes: 43 | ``` 44 | {% picture example.jpg --picture class="some classes" --img id="example" %} 45 | ``` 46 | 47 | * Crop to a 16:9 aspect ratio (Will keep the part of the image "most likely to 48 | draw human attention"): 49 | ``` 50 | {% picture example.jpg 16:9 %} 51 | ``` 52 | 53 | * Crop to a 1:1 aspect ratio, keeping the middle, with alt text: 54 | ``` 55 | {% picture thumbnail example.jpg 1:1 center --alt Example Image %} 56 | ``` 57 | 58 | * Crop the same image multiple times: 59 | ``` 60 | {% picture example.jpg 16:9 tablet: example.jpg 4:3 mobile: example.jpg 1:1 %} 61 | ``` 62 | 63 | * Use filenames with spaces: 64 | ``` 65 | {% picture "some example.jpg" mobile: other\ example.jpg %} 66 | ``` 67 | 68 | * Use line breaks to make a complicated tag manageable: 69 | ``` 70 | {% 71 | picture 72 | hero 73 | example.jpg 16:9 entropy 74 | tablet: example2.jpg 3:2 75 | mobile: example3.jpg 1:1 76 | --alt Happy Puppy 77 | --picture class="hero" 78 | --link / 79 | %} 80 | ``` 81 | {% endraw %} 82 | -------------------------------------------------------------------------------- /docs/users/liquid_tag/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 2 3 | --- 4 | 5 | # Tag Usage 6 | 7 | This section describes how to use JPT's liquid tag ({% raw %} `{% picture (...) 8 | %}` {% endraw %}); what options it takes and what kind of information you can pass 9 | through it to influence the the final HTML and generated images. 10 | 11 | ## Format 12 | 13 | {% raw %} 14 | `{% picture [preset] (image) [crop] [alternate images & crops] [attributes] %}` 15 | {% endraw %} 16 | 17 | The only required argument is the base image. Line breaks and extra spaces are 18 | fine, and you can use liquid variables anywhere. 19 | 20 | * `preset` - Select a recipe/blueprint from the ones you have defined in 21 | `presets`. Will use `default` if not specified. 22 | 23 | * `(image)` - required. 24 | 25 | * `crop` - Aspect ratio & keep settings. 26 | 27 | * `alternate images & crops` - Art Direction; show different images on different 28 | devices. Give in order of ascending specificity. 29 | 30 | * `attributes` - Add css classes, data-attributes, or wrap the whole thing in an 31 | anchor tag. 32 | -------------------------------------------------------------------------------- /docs/users/notes/git_lfs.md: -------------------------------------------------------------------------------- 1 | # Git LFS 2 | 3 | I'm Putting this here because it bit me: If you want to use git LFS, make sure that your hosting 4 | provider makes those images available during the build process. Netlify, for example, does not. 5 | You won't find this out until you have gone through the entire migration process and try to deploy 6 | for the first time. 7 | 8 | -------------------------------------------------------------------------------- /docs/users/notes/html_attributes.md: -------------------------------------------------------------------------------- 1 | # HTML attributes 2 | 3 | Jekyll Picture Tag has comprehensive attribute support for all generated HTML. You can add 4 | attributes both through the [liquid tag](../liquid_tag/index.md), 5 | and the [preset](../presets/html_attributes.md) (scroll down a bit). 6 | -------------------------------------------------------------------------------- /docs/users/notes/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 5 3 | --- 4 | # Notes and FAQ 5 | 6 | {% include list.liquid %} 7 | -------------------------------------------------------------------------------- /docs/users/notes/kramdown_bug.md: -------------------------------------------------------------------------------- 1 | # Extra {::nomarkdown} tags or mangled HTML? 2 | 3 | ## TLDR up front 4 | 5 | There's a bug involving `` tags wrapped in `` tags which is not in 6 | my power to fix. 7 | 8 | * If you're getting extra `{::nomarkdown}` tags floating around your images, add `nomarkdown: 9 | false` to either the relevant preset or under `picture` in `_config.yml`. 10 | 11 | * If you're getting mangled HTML when trying to wrap images with anchor tags, add `nomarkdown: 12 | true` to the preset. 13 | 14 | ## What's going on here: 15 | 16 | Kramdown is Jekyll's default markdown parser. Kramdown gets grumpy when you give it a block level 17 | element (such as a ``) surrounded by a span level element (such as an ``), and horribly 18 | mangles it. The fix for this is to tell Kramdown to chill with a `{::nomarkdown}..{:/nomarkdown}` 19 | wrapper. 20 | 21 | Jekyll Picture Tag can be called from many different places: a markdown file, an HTML file, an HTML 22 | layout for a markdown file, and an HTML include, to name a few. JPT tries its best to determine 23 | whether its output will be parsed by Kramdown or not, but Jekyll itself doesn't make this 24 | particularly easy which results in some false positives. (The one I'm most aware of is when a 25 | markdown file uses an HTML layout which includes a picture tag.) 26 | 27 | Unfortunately, I don't see an easy way to fix this. We've gotten this far mostly by trial and error. 28 | I'll continue to work on improving the autodetection, but you can override this behavior explicitly. 29 | 30 | ## The fix: 31 | 32 | By default, JPT will add a `{::nomarkdown}` tag if all of the following are true: 33 | * It thinks it's called from a markdown page 34 | * The image will be wrapped in an anchor tag (i.e. `link_source_image:` or a `--link` parameter) 35 | * This behavior hasn't been explicitly disabled. 36 | 37 | You can disable nomarkdown tags globally by setting `nomarkdown: false` under the `picture:` key in 38 | `_config.yml`. 39 | 40 | You can enable or disable markdown tags per preset by adding `nomarkdown: true|false` to them. 41 | **This setting overrides everything else, both JPT autodetection and the global setting.** 42 | -------------------------------------------------------------------------------- /docs/users/notes/managing_images.md: -------------------------------------------------------------------------------- 1 | # Managing Generated Images 2 | 3 | Jekyll Picture Tag creates resized versions of your images when you build the 4 | site. It uses a caching system to speed up site compilation, and re-uses images 5 | as much as possible. Filenames take the following format: 6 | 7 | `(original name without extension)-(width)-(id-string).(filetype)` 8 | 9 | Try to use a base image that is larger than the largest resized image you need. 10 | Jekyll Picture Tag will warn you if a base image is too small, and won't upscale 11 | images. 12 | 13 | By specifying a `source` directory that is ignored by Jekyll you can prevent 14 | huge base images from being copied to the compiled site. For example, `source: 15 | assets/images/_fullsize` and `output: generated` will result in a compiled site 16 | that contains resized images but not the originals. Note that this will break 17 | source image linking, if you wish to enable it. (Can't link to images that 18 | aren't public!) 19 | 20 | The `output` directory is never deleted by Jekyll. You may want to empty it once 21 | in awhile, to clear out unused images. 22 | -------------------------------------------------------------------------------- /docs/users/notes/migration_2.md: -------------------------------------------------------------------------------- 1 | --- 2 | --- 3 | # Migrating from 1.x to 2.x 4 | 5 | There are a few breaking changes from 1.x versions, but they've been minimized and hopefully they 6 | won't affect you too badly. This is a guide to transitioning an existing site; We don't go into all 7 | the new features here, except where they replace or modify existing ones. 8 | 9 | - For easy skimming, anything with a bullet point (like this line) is something you need to 10 | check/do. 11 | 12 | ## Libvips 13 | 14 | - Install Libvips, both in development and production. Any reasonably recent version will do. 15 | 16 | We still fall back to ImageMagick when Vips doesn't support a given image format, so there's no 17 | reason to uninstall it. However, we no longer require version 7. Version 6+ is fine, which makes 18 | deployments involving Ubuntu much easier. 19 | 20 | ## Jekyll 4.0+ 21 | 22 | - Update to Jekyll 4.x 23 | 24 | We're removing support for versions of Jekyll before 4.0. I did it inadvertently awhile ago with the 25 | fast_build setting, now it's official. If this causes you a great deal of pain, speak up and we'll 26 | look into supporting older versions. 27 | 28 | ## Ruby 2.6+ 29 | 30 | - Ensure you're running Ruby 2.6 or later. 31 | 32 | While Jekyll supports 2.4, it's officialy EOL and 2.5 (our previous target) is in security 33 | maintenance only. Since I want major version releases to be as rare as possible, we're making this 34 | move now. Again, speak up if this causes a great deal of pain. 35 | 36 | ## Image quality & write options. 37 | 38 | - If you have set `quality:` in a preset, it will stop having an effect for webp, avif, and jp2 39 | images. You need to set `format_quality:` instead. 40 | 41 | Previously, all image formats used a default quality of 75. We have now set a default quality for 3 42 | formats: 43 | 44 | ```yml 45 | format_quality: 46 | webp: 50 47 | avif: 30 48 | jp2: 30 49 | ``` 50 | 51 | Since `format_quality` overrides `quality`, your `quality` setting won't affect those formats 52 | anymore. 53 | 54 | - Lossless webp or avif was previously accomplished by setting quality to 100. Now, that is 55 | accomplished with an image option: 56 | 57 | ```yml 58 | #_data/picture.yml 59 | presets: 60 | 61 | my_preset: 62 | image_options: 63 | webp: 64 | lossless: true 65 | ``` 66 | 67 | ## Setting names changing 68 | 69 | In `_data/picture.yml`, 70 | - `markup_presets` is now `presets` 71 | - `media_presets` is now `media_queries`. 72 | 73 | Go check, especially if you've been using JPT for awhile. We renamed them several versions ago, but 74 | the old names were still supported until now. If you get a bunch of 'preset not found' warnings, 75 | this is probably why. 76 | 77 | 78 | ## Crop changes 79 | 80 | - Anywhere you've set a crop geometry in any format other than `w:h`, remove or change it. This 81 | could be in both tags and presets. 82 | - Anywhere you've set a crop gravity such as `north` or `southeast`, remove it. This could also be 83 | in both tags and presets. 84 | - Build the site, look through cropped images and decide if you like the results. Adjust the new 85 | `keep` setting if desired. 86 | 87 | We now use the Libvips smartcrop feature which does some magic to keep the most interesting part. 88 | `gravity` is now `keep` (as in which part of the image to keep), and your options are `attention`, 89 | `entropy`, or `centre`/`center`. The default is `attention`, and it works pretty well in my testing 90 | so far. 91 | 92 | If you can't get satisfactory results with those options, you'll have to use a proper editor. JPT is 93 | not one, and the old crop feature went too far down the road of trying to be. 94 | 95 | ## Naming of presets and media queries 96 | 97 | - If you have any presets or media queries with names that start with `jpt-`, change them. 98 | 99 | We're cordoning off a namespace for built-in ones. 100 | -------------------------------------------------------------------------------- /docs/users/presets/cropping.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 7 3 | --- 4 | 5 | # Cropping 6 | 7 | ## Crop & Media Crop 8 | 9 | _Format:_ 10 | 11 | ```yaml 12 | crop: (aspect ratio) 13 | media_crop: 14 | (media_preset): (aspect ratio) 15 | (media_preset): (aspect ratio) 16 | (...) 17 | ``` 18 | 19 | _Example:_ 20 | 21 | ```yaml 22 | crop: '16:9' 23 | media_crop: 24 | tablet: '3:2' 25 | mobile: '1:1' 26 | ``` 27 | 28 | Crop aspect ratio, given either generally or for specific media presets. The 29 | hierarchy is: `tag argument` > `media_crop:` > `crop:`. 30 | 31 | This setting accepts the same arguments as the `crop` 32 | [tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop). 33 | 34 | ## Keep & Media Keep 35 | 36 | ```yaml 37 | keep: (measure) 38 | media_keep: 39 | (media_preset): (measure) 40 | (media_preset): (measure) 41 | (...) 42 | ``` 43 | 44 | _Example:_ 45 | 46 | ```yaml 47 | keep: attention 48 | media_gravity: 49 | tablet: entropy 50 | mobile: center 51 | ``` 52 | 53 | Which part of the image to keep when cropping, given either generally or for specific media presets. 54 | The hierarchy is: `tag argument` > `media_keep:` > `keep:` > `attention` (default). 55 | 56 | This setting accepts the same arguments as the `keep` [tag parameter]({{ site.baseurl 57 | }}/users/liquid_tag/argument_reference/crop): 58 | * `center` or `centre` 59 | * `attention` 60 | * `entropy` 61 | -------------------------------------------------------------------------------- /docs/users/presets/default.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 14 3 | --- 4 | 5 | # Default preset 6 | 7 | Here are the default preset settings: 8 | 9 | ```yml 10 | presets: 11 | default: 12 | markup: auto 13 | formats: [original] 14 | widths: [400, 600, 800, 1000] 15 | fallback_width: 800 16 | fallback_format: original 17 | noscript: false 18 | link_source: false 19 | quality: 75 20 | format_quality: 21 | webp: 50 22 | avif: 30 23 | jp2: 30 24 | strip_metadata: true 25 | image_options: 26 | avif: 27 | compression: av1 28 | speed: 8 29 | data_sizes: true 30 | keep: attention 31 | dimension_attributes: false 32 | ``` 33 | -------------------------------------------------------------------------------- /docs/users/presets/examples.md: -------------------------------------------------------------------------------- 1 | --- 2 | sort: 2 3 | --- 4 | # Examples 5 | 6 | The following example media queries & presets (except for `default`) are built-in with a `jpt-` 7 | prefix. For example, the `desktop` media query below can be used with `jpt-desktop`, and the `webp` 8 | preset below can be used with `jpt-webp`. 9 | 10 | ```yaml 11 | # _data/picture.yml 12 | 13 | # These are used in several places. You likely want to enter whatever CSS media queries your site 14 | # uses here. 15 | media_queries: 16 | mobile: 'max-width: 480px' 17 | tablet: 'max-width: 768' 18 | laptop: 'max-width: 1024px' 19 | desktop: 'max-width: 1200' 20 | wide: 'min-width: 1201' 21 | 22 | presets: 23 | # This entry is purely an example. It is not the default JPT preset, nor is it available as a 24 | # built-in. 25 | default: 26 | formats: [webp, original] # Order matters! 27 | widths: [200, 400, 800, 1200, 1600] # Image widths, in pixels. 28 | 29 | # The sizes attribute is both important, and impossible to offer good defaults for. You need to 30 | # learn about it. Short version: Web browsers parse web pages line-by-line. When they run into 31 | # an external asset they must download, they start that process immediately, without waiting to 32 | # finish rendering the page. This means that at the point in time when the browser must decide 33 | # which image to download, it has no clue how large that image will be on the page. The sizes 34 | # attribute is how we tell it. 35 | # 36 | # If you do not provide this, the web browser will assume the image is 100vw (100% the width of 37 | # the viewport.) 38 | # 39 | # This doesn't have to be pixel-perfect, just close enough for the browser to make a good 40 | # choice. Keys are media queries defined above, values are how large the image will be when 41 | # that media query is true. You can't use % (percentage width of the parent container) for the 42 | # same reason we have to do this at all. 43 | sizes: 44 | mobile: calc(100vw - 16px) 45 | tablet: 80vw 46 | 47 | # Size is unconditional; provided either after all conditional sizes (above) or alone. If you 48 | # only have a 'size' (no 'sizes'), and it's a constant (px, em, or rem), you should use a 49 | # pixel-ratio srcset. 50 | size: 800px 51 | 52 | link_source: true # wrap images in a link to the original source image. 53 | dimension_attributes: true # Page reflow begone! 54 | 55 | # You can add any HTML attribute you like, to any HTML element which JPT creates: 56 | attributes: 57 | # parent refers to the outermost tag; if it's present, otherwise the . 58 | parent: 'data-downloadable="true"' 59 | picture: 'class="awesome" data-volume="11"' 60 | img: 'class="some-other-class"' 61 | a: 'class="image-link"' 62 | 63 | # You can use this as jpt-webp. All following presets follow the same pattern. 64 | webp: 65 | formats: [webp, original] 66 | 67 | # Avif is the new hotness coming down the pipe. Browser support is bad and they are slow to 68 | # generate, but you get good file sizes even compared to webp of similar quality. 69 | avif: 70 | formats: [avif, webp, original] 71 | 72 | # Your build times will suffer, but everyone is happy. 73 | loaded: 74 | formats: [avif, jp2, webp, original] 75 | dimension_attributes: true 76 | 77 | # This is an example of how you would create a 'multiplier' based srcset; useful when an image 78 | # will always be the same size on all screens (icons, graphics, thumbnails, etc), but you'd like 79 | # to supply higher resolution images to devices with higher pixel ratios. 80 | thumbnail: 81 | base_width: 250 # How wide the 1x image should be. 82 | pixel_ratios: [1, 1.5, 2] # Which multipliers to target. 83 | fallback_width: 250 # The default is 800, which is probably too big. 84 | formats: [webp, original] 85 | attributes: 86 | picture: 'class="thumbnail"' 87 | 88 | # Another pixel-ratio example. 89 | avatar: 90 | # Say your layout demands a square: 91 | crop: 1:1 92 | base_width: 100 93 | pixel_ratios: [1, 1.5, 2] 94 | fallback_width: 100, 95 | 96 | # Here's an example of how you'd configure JPT to work with something like lazyload: 97 | # https://github.com/verlok/lazyload 98 | # Remember to add a sizes attribute, unless it's close to 100vw all the time. 99 | lazy: 100 | markup: data_auto 101 | formats: [webp, original] 102 | noscript: true # add a fallback image inside a