{"id":13612154,"url":"https://github.com/mslinn/jekyll_img","last_synced_at":"2025-10-27T05:30:54.898Z","repository":{"id":65273278,"uuid":"589000761","full_name":"mslinn/jekyll_img","owner":"mslinn","description":"This versatile plugin embeds responsive images using the \u003cpicture/\u003e element in documents and pages with alignment options,   flexible resizing, default styling, overridable styling, an optional caption, and an optional URL.","archived":false,"fork":false,"pushed_at":"2024-12-22T14:59:35.000Z","size":654,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-01T02:22:49.065Z","etag":null,"topics":["jekyll","jekyll-tag"],"latest_commit_sha":null,"homepage":"https://www.mslinn.com/jekyll_plugins/jekyll_img.html","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mslinn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-14T18:33:09.000Z","updated_at":"2024-12-22T14:59:38.000Z","dependencies_parsed_at":"2023-11-19T21:28:09.682Z","dependency_job_id":"e5d36275-68c2-457c-980c-879c6a194139","html_url":"https://github.com/mslinn/jekyll_img","commit_stats":{"total_commits":42,"total_committers":2,"mean_commits":21.0,"dds":0.09523809523809523,"last_synced_commit":"59c3ffaeefbf705392deaf7c276d4fe0fd7473b4"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mslinn%2Fjekyll_img","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mslinn%2Fjekyll_img/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mslinn%2Fjekyll_img/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mslinn%2Fjekyll_img/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mslinn","download_url":"https://codeload.github.com/mslinn/jekyll_img/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238437619,"owners_count":19472448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jekyll","jekyll-tag"],"created_at":"2024-08-01T20:00:23.510Z","updated_at":"2025-10-27T05:30:54.892Z","avatar_url":"https://github.com/mslinn.png","language":"Ruby","funding_links":[],"categories":["Images \u0026 Pictures"],"sub_categories":[],"readme":"# `jekyll_img` [![Gem Version](https://badge.fury.io/rb/jekyll_img.svg)](https://badge.fury.io/rb/jekyll_img)\n\n\n`Jekyll_img` is a Jekyll plugin that embeds images in HTML documents, with alignment options,\nflexible resizing, default styling, overridable styling, an optional caption, an optional URL,\nand optional fullscreen zoom on mouseover.\n\nMuliple image formats are supported for each image.\nThe user\u0026rsquo;s web browser determines the formats which it will accept.\nThe most desirable formats that the web browser supports are prioritized.\n\nFor example, if an image is encloded in `webp`, `png` and `gif` filetypes,\nand the user\u0026rsquo;s web browser is relatively recent,\nthen `webp` format will give the fastest transmission and look best.\nOlder browsers, which might not support `webp` format,\nwould give best results for `png` format.\nReally old web browsers would only support the `gif` file type.\n\nPlease read the next section for details.\n\nI explain why the `webp` image format is important in\n[Converting All Images in a Website to `webp` Format](https://mslinn.com/blog/2020/08/15/converting-all-images-to-webp-format.html).\nThat article also provides 2 bash scripts for converting existing images to and from \u003ccode\u003ewebp\u003c/code\u003e format.\n\nSee [demo/index.html](demo/index.html) for examples.\n\n\n## External Images\n\nImages whose `src` attribute starts with `http` are not served from the Jekyll website.\nThe `jekyll_img` plugin generates HTML for external images using an `img` element with a `src`\nattribute as you might expect.\n\n\n## Image Fallback\n\nFor local files (files served from the Jekyll website),\nthe `jekyll_img` plugin generates HTML that falls back to successively less performant\nformats.\nThis is made possible by using a\n[`picture`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture) element.\n\nAt least one version of every image are required.\nSupported filetypes are:\n`svg`, `webp`, `apng`, `png`, `jpg`, `jpeg`, `jfif`, `pjpeg`, `pjp`, `gif`, `tif`, `tiff`, `bmp`, `ico` and `cur`.\n\nFor example, an image file might have the following verions: `blah.webp`, `blah.png` and `blah.jpg`.\nGiven a tag invocation like `{% img src='blah.webp' %}`,\nthe plugin would generate a `picture` element that contains an `img` sub-element with the given `src` attribute,\nand a `source` element for each related image (`blah.png` and `blah.jpg`).\nConceptually, the generated HTML might look something like this:\n\n```html\n\u003cpicture\u003e\n  \u003csource srcset=\"blah.png\" /\u003e\n  \u003csource srcset=\"blah.jpg\" /\u003e\n  \u003cimg src=\"blah.webp\" /\u003e\n\u003c/picture\u003e\n```\n\nIf no filetype is given for the image, `webp` is assumed.\nFor example, these two invocations yield the same result,\nif `blah.webp` exists on the Jekyll website:\n\n```html\n{% img src=\"blah\" %}\n{% img src=\"blah.webp\" %}\n```\n\nIf both `blah.webp` and `blah.png` were available,\nthe above would fetch and display `blah.webp` if the web browser supported `webp` format,\notherwise it would fetch and display `blah.png`.\nIf the browser did not support the `picture` element,\nthe `img src` attribute would be used to specify the image.\n\n\n### Default and Relative Paths\n\nLocal images whose path does not start with a slash are assumed to be relative to `/assets/images`.\nSimply specifying the filename of the image will cause it to be fetched from\n`/assets/images/`.\nFor example, the following all fetch the same image:\n\n```html\n{% img src=\"/assets/images/blah.webp\" %}\n{% img src=\"blah.webp\" %}\n{% img src=\"blah\" %}\n```\n\nTo specify an image in a subdirectory of where the page resides,\nprepend the relative path with a dot (`.`).\n\nFor example, if the current page resides in a [Jekyll collection](https://jekyllrb.com/docs/collections/)\nwith path `/collections/_av_studio/`,\nand an image resides in the `/collections/_av_studio/images` subdirectory,\nthe following would result in the same image being displayed:\n\n```html\n{% img src=\"/av_studio/images/blah\" %}\n{% img src=\"./images/blah\" %}\n```\n\n### Lazy Loading\n\nAn image can be lazily loaded by providing the `lazy` keyword.\nThis feature relies upon the lazy loading capability built into all modern browsers and does not rely upon JavaScript.\n\nFrom [Browser-level image lazy loading for the web](https://web.dev/articles/browser-level-image-lazy-loading#dimension-attributes)\non `web.dev`:\n\n\u003e While the browser loads an image, it doesn't immediately know the image's dimensions,\n\u003e unless they're explicitly specified.\n\u003e To let the browser reserve enough space on a page for images, and avoid disruptive layout shifts,\n\u003e we recommend adding width and height attributes to all  tags.\n\u003e\n\u003e \u0026lt;img src=\"image.png\" loading=\"lazy\" alt=\"…\" width=\"200\" height=\"200\"\u003e\nAlternatively, specify their values directly in an inline style:\n\u003e\n\u003e \u0026lt;img src=\"image.png\" loading=\"lazy\" alt=\"…\" style=\"height:200px; width:200px;\"\u003e\n\nThis would translate to:\n\n```html\n{% img lazy\n  src=\"blah.webp\"\n  style=\"height:200px; width:200px\"\n%}\n```\n\nNote that the image must be fetched in order for HTML `img` attributes `height='auto'` and `width='auto'` to work.\nThus lazy loading is incompatible with a dimension whose value is specified as `auto`.\nThis means that, for lazily loaded images,\n`height` and `width` must have values that are computable without loading the image.\nBecause the Jekyll `img` tag's `size` attribute only specifies the `width` attribute,\nand sets `height` to `auto`, it should not be used with the `lazy` keyword.\n\nThe following examples of implicit and explicit `auto` dimensions will all give problems:\n\n```html\n{% img lazy\n  caption=\"A warning will be written to the logger\"\n  size=\"200px\"\n  src=\"blah.webp\"\n%}\n\n{% img lazy\n  src=\"blah.webp\"\n  style=\"height:auto; width:200px\"\n%}\n\n{% img lazy\n  src=\"blah.webp\"\n  style=\"height:200px; width:auto\"\n%}\n\n{% img lazy\n  src=\"blah.webp\"\n  style=\"height:200px\"\n%}\n\n{% img lazy\n  src=\"blah.webp\"\n  style=\"width:200px\"\n%}\n```\n\n\n### High Priority Loading\n\nAn image can be fetched with high priority by providing the `priority` keyword.\n\nSample usage:\n\n```html\n{% img priority src=\"blah.webp\" %}\n```\n\nThe above generates an HTML `img` tag with a `fetchpriority='high'` attribute.\n\nFrom [Browser-level image lazy loading for the web](https://web.dev/articles/browser-level-image-lazy-loading#loading-priority)\non `web.dev`:\n\n\u003e If you want to increase the fetch priority of an important image, use `fetchpriority=\"high\"`.\n\u003e\n\u003e An image with `loading=\"lazy\"` and `fetchpriority=\"high\"` is still delayed while it's off-screen,\n\u003e and then fetched with a high priority when it's almost within the viewport.\n\u003e This combination isn't really necessary because the browser would likely load that image with high priority anyway.\n\n\nNote that the image must be fetched in order for `img` attributes `height='auto'` and `width='auto'` to work.\nThis means that `height` and `width` must have values that are computable without loading\nthe image or lazy loading will not work properly.\nBecause the `img` tag's `size` attribute only specifies the `width` attribute, and sets `height` to `auto`,\nit should not be used.\n\nSample usage combining lazy and high priority loading:\n\n```html\n{% img lazy priority\n  src=\"blah.webp\"\n  style=\"height:200px; width:200px\"\n%}\n```\n\n\n## Supported Filetypes\n\nThe following are listed in order of priority.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types) for more information.\n\n| Filetype                              | MIME type       |\n| ------------------------------------- | --------------- |\n| `svg`                                 | `image/svg+xml` |\n| `avif`                                | `image/avif`    |\n| `webp`                                | `image/webp`    |\n| `apng`                                | `image/apng`    |\n| `png`                                 | `image/png`     |\n| `jpg`, `jpeg`, `jfif`, `pjpeg`, `pjp` | `image/jpeg`    |\n| `gif`                                 | `image/gif`     |\n| `tif`, `tiff`                         | `image/tiff`    |\n| `bmp`                                 | `image/bmp`     |\n| `ico`, `cur`                          | `image/x-icon`  |\n\nBecause `avif` is problematic as of 2024-01-08 on Firefox, Chrome and Safari, it is not supported yet.\n\n\n## Demo\n\nRun the demo website by typing:\n\n```shell\n$ demo/_bin/debug -r\n```\n\n... and point your web browser to http://localhost:4011\n\n\n## Usage\n\n```html\n{% img [Options] src='path' %}\n```\n\n`Options` are:\n\n- `attribution` See [`jekyll_plugin_support`](https://github.com/mslinn/jekyll_plugin_support#subclass-attribution).\n- `align=\"left|inline|right|center\"` Default value is `inline`\n- `alt=\"Alt text\"` Default value is the `caption` text, if provided\n- `caption=\"A caption\"` No default value\n- `classes=\"class1 class2 classN\"` Extra \u0026lt;img\u0026gt; classes; default is `rounded shadow`\n- `id=\"someId\"` No default value\n- `max-width='eighthsize|fullsize|halfsize|initial|quartersize|XXXYY|XXX%'`\n   Defines width of image.\n  - `initial` is the default behavior.\n  - `eighthsize`, `fullsize`, `halfsize`, and `quartersize` are relative to the enclosing tag's width.\n  - CSS units can also be used, for those cases `XXX` is a float and `YY` is `unit` (see below)\n- `nofollow`  Generates `rel='nofollow'`; only applicable when `url` is specified\n- `width='eighthsize|fullsize|halfsize|initial|quartersize|XXXYY|XXX%'`\n   Defines width of image (alias for `size`).\n  - `initial` is the default behavior.\n  - `eighthsize`, `fullsize`, `halfsize`, and `quartersize` are relative to the enclosing tag's width.\n  - CSS units can also be used, for those cases `XXX` is a float and `YY` is `unit` (see below)\n- `style='css goes here'` CSS style for \u0026lt;img\u0026gt;; no default\n- `target='none|whatever'` Only applicable when `url` is specified; default value is `_blank`\n- `title=\"A title\"` Default value is `caption` text, if provided\n- `url='https://domain.com'` No default value\n- `wrapper_class='class1 class2 classN'` Extra CSS classes for wrapper \u0026lt;div\u0026gt;; no default value\n- `wrapper_style='background-color: black;'` CSS style for wrapper \u0026lt;div\u0026gt;; no default value\n- `zoom` Fullscreen zoom on mouseover; presse escape or click outside image to dismiss\n\n[`unit`](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#numbers_lengths_and_percentages)\nis one of: `Q`, `ch`, `cm`, `em`, `dvh`, `dvw`, `ex`, `in`, `lh`,\n`lvh`, `lvw`, `mm`, `pc`, `px`, `pt`, `rem`, `rlh`, `svh`, `svw`, `vb`,\n`vh`, `vi`, `vmax`, `vmin`, or `vw`.\n\nCSS classes referenced by the `jekyll_img` plugin are in\n[`demo/assets/css/jekyll_img.css`](demo/assets/css/jekyll_img.css) and\n[`demo/assets/css/jekyll_plugin_support.css`](demo/assets/css/jekyll_plugin_support.css).\nCSS marker classes are included, so CSS selectors can be used for additional styling.\n\n\n## Configuration\n\nBy default, errors cause Jekyll to abort.\nYou can allow Jekyll to halt by setting the following in `_config.yml`:\n\n```yaml\nimg:\n  die_on_img_error: true\n  pry_on_img_error: true\n```\n\n\n## Design\n\nThe most significant design issue was the decision that image size and formatting should not change\nwhether it had a caption.\nHTML captions exist within a `\u003cfigure /\u003e` element, which also surrounds the image.\n\nI also wanted to ensure that captions would wrap text under an image,\nand would not be wider than the image they were associated with.\n\nCSS behavior differs for `\u003cfigure /\u003e` and `\u003cimg /\u003e`.\nFor example, centering, floating right and left.\nThat means the CSS and where it would need to be applied are completely different for\nnaked `\u003cimg /\u003e` and `\u003cfigure /\u003e` tags.\nHandling all possible situations of these two scenarios would significantly raise the complexity of the plugin code.\nI know, because I went down that rabbit hole.\n\n\n### Wrapper \u0026lt;div /\u0026gt;\n\nTo make the plugin code more manageable,\nthe plugin always encloses the generated HTML \u0026 CSS within a wrapper `\u003cdiv /\u003e`.\nThe wrapper allows for a simple, consistent approach regardless of whether a caption is generated or not.\n\nThe wrapper width is identical to the displayed image width.\nWithin the wrapper `\u003cdiv /\u003e`, the embedded `\u003cimg /\u003e` is displayed with `width=100%`.\nIf a caption is required, the generated `\u003cfigure /\u003e` only makes the space taken by the generated HTML longer;\nthe image\u0026rsquo;s width and height are not affected.\n\nThe wrapper will not exceed the width of the tag that encloses it if the `width` parameter has values\n`eighthsize`, `fullsize`, `halfsize`, `initial` or `quartersize`.\nYou can also use the `max-width` option.\n\nThe wrapper's width can be defined independently of its enclosing tag by using\n[CSS units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#numbers_lengths_and_percentages)\nfor the `size` parameter:\n`Q`, `ch`, `cm`, `em`, `dvh`, `dvw`, `ex`, `in`, `lh`,\n`lvh`, `lvw`, `mm`, `pc`, `px`, `pt`, `rem`, `rlh`, `svh`, `svw`, `vb`,\n`vh`, `vi`, `vmax`, `vmin`, or `vw`.\nUsing CSS units means that large enough values could cause the image to exceed the width of its enclosing tag.\n\n\n## Installation\n\nAdd this line to your Jekyll project's `Gemfile`, within the `jekyll_plugins` group:\n\n```ruby\ngroup :jekyll_plugins do\n  gem 'jekyll_img'\nend\n```\n\nAnd then execute:\n\n```shell\n$ bundle\n```\n\n\n## Additional Information\n\nMore information is available on\n[Mike Slinn\u0026rsquo;s website](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html).\n\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies.\n\nYou can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\n\nTo build and install this gem onto your local machine, run:\n\n```shell\n$ bundle exec rake install\njekyll_img 0.1.0 built to pkg/jekyll_img-0.1.0.gem.\njekyll_img (0.1.0) installed.\n```\n\nExamine the newly built gem:\n\n```shell\n$ gem info jekyll_img\n\n*** LOCAL GEMS ***\n\njekyll_img (0.1.0)\n    Author: Mike Slinn\n    Homepage:\n    https://github.com/mslinn/jekyll_img\n    License: MIT\n    Installed at: /home/mslinn/.gems\n\n    Generates Jekyll logger with colored output.\n```\n\n\n### Debugging\n\nYou can cause `pry` to open when an `ImgError` is raised by setting `pry_on_img_error` in `_config.yml`.\n`Pry_on_img_error` has priority `die_on_img_error`.\n\n```yaml\njekyll_img:\n  die_on_img_error: false # Default value is false\n  pry_on_img_error: true # Default value is false\n```\n\n\n### Testing\n\nExamine the output by running:\n\n```shell\n$ demo/_bin/debug -r\n```\n\n... and pointing your web browser to http://localhost:4444/\n\n### Unit Tests\n\nEither run `rspec` from Visual Studio Code's *Run and Debug* environment\n(\u003ckbd\u003eCtrl\u003c/kbd\u003e-\u003ckbd\u003eshift\u003c/kbd\u003e-\u003ckbd\u003eD\u003c/kbd\u003e) and view the *Debug Console* output,\nor run it from the command line:\n\n```shell\n$ rspec\n```\n\n### Build and Push to RubyGems\n\nTo release a new version,\n\n1. Update the version number in `version.rb`.\n2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.\n3. Run the following:\n\n   ```shell\n   $ bundle exec rake release\n   ```\n\n     The above creates a git tag for the version, commits the created tag,\n     and pushes the new `.gem` file to [RubyGems.org](https://rubygems.org).\n\n\n## Contributing\n\n1. Fork the project\n2. Create a descriptively named feature branch\n3. Add your feature\n4. Submit a pull request\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmslinn%2Fjekyll_img","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmslinn%2Fjekyll_img","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmslinn%2Fjekyll_img/lists"}