`jekyll_img`
[](https://badge.fury.io/rb/jekyll_img)
===========
`Jekyll_img` is a Jekyll plugin that displays images,
and provides support for captions and URLs.
See [demo/index.html](demo/index.html) for examples.
Run the demo website by typing:
```shell
$ demo/_bin/debug -r
```
... and point your web browser to http://localhost:4444
## Usage
{% img [Options] src='path' %}
`Options` are:
- `align="left|inline|right|center"` Default value is `inline`
- `alt="Alt text"` Default value is the `caption` text, if provided
- `caption="A caption"` No default value
- `classes="class1 class2 classN"` Extra <img> classes; default is `rounded shadow`
- `id="someId"` No default value
- `nofollow` Generates `rel='nofollow'`; only applicable when `url` is specified
- `size='eighthsize|fullsize|halfsize|initial|quartersize|XXXYY|XXX%'`
Defines width of image.
- `initial` is the default behavior.
- `eighthsize`, `fullsize`, `halfsize`, and `quartersize` are relative to the enclosing tag's width.
- CSS units can also be used, for those cases `XXX` is a float and `YY` is `unit` (see below)
- `style='css goes here'` CSS style for <img>; no default
- `target='none|whatever'` Only applicable when `url` is specified; default value is `_blank`
- `title="A title"` Default value is `caption` text, if provided
- `url='https://domain.com'` No default value
- `wrapper_class='class1 class2 classN'` Extra CSS classes for wrapper <div>; no default value
- `wrapper_style='background-color: black;'` CSS style for wrapper <div>; no default value
[`unit`](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#numbers_lengths_and_percentages) is one of: `Q`, `ch`, `cm`, `em`, `dvh`, `dvw`, `ex`, `in`, `lh`,
`lvh`, `lvw`, `mm`, `pc`, `px`, `pt`, `rem`, `rlh`, `svh`, `svw`, `vb`,
`vh`, `vi`, `vmax`, `vmin`, or `vw`.
CSS classes referenced by the `jekyll_img` plugin are at the bottom of [demo/assets/css/style.css](demo/assets/css/style.css). CSS marker classes are included, so CSS selectors can be used for additional styling.
## Design
The most significant design issue was the decision that image size and formatting should not change
whether it had a caption.
HTML captions exist within a `` element, which also surrounds the image.
I also wanted to ensure that captions would wrap text under an image,
and would not be wider than the image they were associated with.
CSS behavior differs for `` and ``.
For example, centering, floating right and left.
That means the CSS and where it would need to be applied are completely different for
naked `` and `` tags.
Handling all possible situations of these two scenarios would significantly raise the complexity of the plugin code. I know, because I went down that rabbit hole.
### Wrapper <div />
To make the plugin code more manageable,
the plugin always encloses the generated HTML & CSS within a wrapper `
`.
The wrapper allows for a simple, consistent approach regardless of whether a caption is generated or not.
The wrapper width is identical to the displayed image width.
Within the wrapper ``, the embedded `` is displayed with `width=100%`.
If a caption is required, the generated `` only makes the space taken by the generated HTML longer;
the image width and height is not affected.
The wrapper will not exceed the width of the tag that encloses it if the `size` parameter has values `eighthsize`, `fullsize`, `halfsize`, `initial` or `quartersize`.
The wrapper's width can be defined independently of its enclosing tag by using [CSS units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#numbers_lengths_and_percentages) for the `size` parameter:
`Q`, `ch`, `cm`, `em`, `dvh`, `dvw`, `ex`, `in`, `lh`,
`lvh`, `lvw`, `mm`, `pc`, `px`, `pt`, `rem`, `rlh`, `svh`, `svw`, `vb`,
`vh`, `vi`, `vmax`, `vmin`, or `vw`.
Using CSS units means that large enough values could cause the image to exceed the width of its enclosing tag.
## Installation
Add this line to your Jekyll project's Gemfile, within the `jekyll_plugins` group:
```ruby
group :jekyll_plugins do
gem 'jekyll_img'
end
```
Also add it to `_config.yml`:
```yaml
plugins:
- jekyll_img
```
And then execute:
$ bundle install
## Additional Information
More information is available on
[Mike Slinn’s website](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html).
## Development
After checking out the repo, run `bin/setup` to install dependencies.
You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To build and install this gem onto your local machine, run:
```shell
$ bundle exec rake install
jekyll_img 0.1.0 built to pkg/jekyll_img-0.1.0.gem.
jekyll_img (0.1.0) installed.
```
Examine the newly built gem:
```shell
$ gem info jekyll_img
*** LOCAL GEMS ***
jekyll_img (0.1.0)
Author: Mike Slinn
Homepage:
https://github.com/mslinn/jekyll_img
License: MIT
Installed at: /home/mslinn/.gems
Generates Jekyll logger with colored output.
```
### Testing
Examine the output by running:
```shell
$ demo/_bin/debug -r
```
... and pointing your web browser to http://localhost:4444/
### Unit Tests
Either run `rspec` from Visual Studio Code's *Run and Debug* environment
(Ctrl-shift-D) and view the *Debug Console* output,
or run it from the command line:
```shell
$ rspec
```
### Build and Push to RubyGems
To release a new version,
1. Update the version number in `version.rb`.
2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
3. Run the following:
```shell
$ bundle exec rake release
```
The above creates a git tag for the version, commits the created tag,
and pushes the new `.gem` file to [RubyGems.org](https://rubygems.org).
## Contributing
1. Fork the project
2. Create a descriptively named feature branch
3. Add your feature
4. Submit a pull request
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).