update blog post for image usage
This commit is contained in:
madrilene
parent
8f381ba436
commit
2662f44d41
1 changed files with 92 additions and 26 deletions
|
|
@ -3,32 +3,65 @@ title: 'Post with an image'
|
|||
description: "You can use Markdown, a Nunjucks shortcode or pure HTML to add images to your posts and pages."
|
||||
date: 2025-01-09
|
||||
tags: ['image', 'feature']
|
||||
image: './src/assets/images/gallery/asturias-1.jpg'
|
||||
image: '/assets/images/gallery/asturias-1.jpg'
|
||||
alt: 'A picturesque valley showcasing majestic mountains and lush forests, creating a serene and captivating landscape'
|
||||
credit: A photo I took.
|
||||
---
|
||||
|
||||
## With HTML Transform
|
||||
Using the powerful Eleventy Image plugin, we have three ways to optimize images: HTML Transform, Markdown syntax, and a Nunjucks shortcode.
|
||||
|
||||
Transforms any `<img>` or `<picture>` tags in HTML files as a post-processing step.
|
||||
## HTML Transform
|
||||
|
||||
```jinja2
|
||||
Transforms any `<img>` or `<picture>` tags in HTML files as a post-processing step. Find the defaut settings diretcly in `eleventy.config.js`.
|
||||
|
||||
```html
|
||||
<img src="./co-located-image.jpg" alt="alt text">
|
||||
<img src="/assets/images/absolute-path-image.jpg" alt="alt text">
|
||||
```
|
||||
|
||||
We can pass in overrides for every instance and use attributes like loading and decoding
|
||||
We can pass in overrides for every instance and use attributes. By default all images are set to be lazy loaded, but we can override this by directly setting `loading="eager"` and `decoding="sync" `on the `<img>` element.
|
||||
|
||||
```jinja2
|
||||
Another thing to note is the `widths: ['auto']` setting, which by default only includes the original size image. You can set the dedicated `widths` to be used by adding `eleventy:widths="800,1200"` on the element. For images with [Markdown syntax](/blog/post-with-an-image/#markdown-syntax), I set fixed `widths` so we don't need to set a value on every instance.
|
||||
|
||||
`sizes` defaults to `auto`, which is applied to all lazy loading images. For eager-loading images, the value is equivalent to `100vw` See: https://github.com/whatwg/html/pull/8008. We can _still_ overwrite this, by setting the `sizes` attribute directly on the `<img>` element, with something specific like `sizes="(max-width: 615px) 50vw, 100vw"`.
|
||||
|
||||
```html
|
||||
<img src="./co-located-image.jpg" alt="alt text" eleventy:widths="200,600" loading="eager" decoding="sync">
|
||||
```
|
||||
|
||||
<img src="./asturias-1.jpg" alt="A picturesque valley showcasing majestic mountains and lush forests, creating a serene and captivating landscape" eleventy:widths="200,600" loading="eager" decoding="sync">
|
||||
<img src="./asturias-1.jpg" alt="A picturesque valley showcasing majestic mountains and lush forests, creating a serene and captivating landscape" eleventy:widths="200,600" sizes="(max-width: 615px) 50vw, 100vw" loading="eager" decoding="sync">
|
||||
|
||||
This makes this syntax equally powerfull as the [shortcode](/blog/post-with-an-image/#nunjucks-shortcode), and easier to read - with the extra benefit that we can use both relative and absolute image sources.
|
||||
Only "downside" ist, that it comes with a higher build cost due to the post-processing step.
|
||||
|
||||
More info: https://www.11ty.dev/docs/plugins/image/#html-transform
|
||||
|
||||
## With a shortcode
|
||||
## Markdown syntax
|
||||
|
||||
The shortcode is for situations where you need full control of the output of the image. The most basic version contains the path to the image and alt text (can be an empty string if the image is decorative).
|
||||
This also uses [Image HTML Transform ](https://www.11ty.dev/docs/plugins/image/#html-transform).
|
||||
The markdown sytnax for images creates the `<img>` element the plugin is looking for, and then transforms it to the `<picture>` elemenr (if more than one format is set).
|
||||
|
||||
In `src/_config/plugins/markdown.js` I customized the Markdown rendering for images slightly. What normally would become a `title` attribute is used to create a caption. Note that I set a fixed `widths` value instead of `auto` as the default.
|
||||
|
||||
```markdown
|
||||
|
||||
 'I used a portrait lens for this one'
|
||||
```
|
||||
|
||||
|
||||
|
||||
You can also add custom attributes here, to overwrite the default `widths`, have the image eagerly loaded, or add a class etc.
|
||||
|
||||
```markdown
|
||||
{attrs}
|
||||
{loading="eager" decoding="sync" eleventy:widths="400" class="grayscale"}
|
||||
```
|
||||
|
||||
{loading="eager" decoding="sync" eleventy:widths="400" class="grayscale"}
|
||||
|
||||
## Nunjucks shortcode
|
||||
|
||||
The most basic version contains the path to the image (absolute) and alt text (can be an empty string if the image is decorative).
|
||||
|
||||
{% raw %}
|
||||
|
||||
|
|
@ -38,39 +71,72 @@ The shortcode is for situations where you need full control of the output of the
|
|||
|
||||
{% endraw %}
|
||||
|
||||
It defaults to `loading = 'lazy'`, the picture element gets its set of images from `widths = [650, 960, 1200]` and compares to a condition of `100vw`.
|
||||
You can pass in manually all the conditions, add `null` to skip.
|
||||
You can pass classes to the outer container ( `<picture>` or `<figure>` element), and to the `<img>` element itself.
|
||||
It defaults to `loading = 'lazy'`, the picture element gets its set of images from `widths=[650,960,1200]` and compares to a condition of `sizes="auto"`.
|
||||
You can pass in manually all the conditions, add `null` to skip. The arguments include classes for the outer container ( `<picture>` or `<figure>` element), and for the `<img>` element.
|
||||
|
||||
The shortcode is stored in `src/_config/shortcodes/image.js`.
|
||||
|
||||
{% raw %}
|
||||
|
||||
```jinja2
|
||||
{% image "path to image", "alt text", "caption text", "eager", "container class names", "img class names", "(min-width:30em) 50vw, 100vw", [200, 400] %}
|
||||
{% image "path to image", "alt text", "caption text", "eager", "container class names", "img class names", [200, 400], "(min-width:30em) 50vw, 100vw" %}
|
||||
{% image "path to image", "alt text", null, "eager" %}
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
{% image "./src/assets/images/gallery/asturias-3.jpg", "A traditional Asturian village with it's raised granaries, surrounded by lush green hills and mountains", "What a nice old house in black and white", "lazy", "text-center", "grayscale", "(min-width:30em) 50vw, 100vw", [200, 400] %}
|
||||
{% image "/assets/images/gallery/asturias-3.jpg", "A traditional Asturian village with it's raised granaries, surrounded by lush green hills and mountains", "What a nice old house in black and white", "lazy", "text-center", "grayscale", [200, 400], "(min-width:30em) 50vw, 100vw" %}
|
||||
|
||||
## Markdown syntax
|
||||
Example: predefine `widths` and `sizes` using Nunjuck's `set` tag or front matter fields, and dynamically get the image path, like I do in the built-with template.
|
||||
|
||||
This also uses [Image HTML Transform ](https://www.11ty.dev/docs/plugins/image/#html-transform). As the usual markdown sytnax for images creates the image element the plugin is looking for, it transforms it to the rich picture format.
|
||||
{% raw %}
|
||||
|
||||
In `src/_config/plugins/markdown.js` I customized the Markdown rendering for images slightly. What normally would become a `title` attribute is used to create a caption.
|
||||
|
||||
In Markdown files like this blog post here, the Markdown syntax or plain HTML works best.
|
||||
|
||||
```markdown
|
||||
|
||||
 'I used a portrait lens for this one'
|
||||
```jinja2
|
||||
{% image "/assets/images/screenshots/" + site.filename + ".jpg", site.name, null, "lazy", null, null, widths, sizes %}
|
||||
```
|
||||
|
||||
|
||||
{% endraw %}
|
||||
|
||||
Recommended reads:
|
||||
## Comparing Shortcode and HTML Transform
|
||||
|
||||
The shortcode can be much terser than the HTML syntax. It also includes the `slot="image"` attribute for seamless WebC component integration. However, it's less readable, and you must carefully order all arguments. On the other hand, the HTML syntax is much more readable and easier to maintain.
|
||||
|
||||
As for the higher build cost of post-processing, the shortcode images are being skipped using the `eleventy:ignore` attribute, but still seem to be processed somehow. I have yet to figure out if this is avoidable. If you set the `eleventy:ignore` on an HTML image though, it _is_ completely skipped and excluded from the processed images.
|
||||
|
||||
**These two approaches produce (almost) the same output:**
|
||||
|
||||
{% raw %}
|
||||
|
||||
```jinja2
|
||||
{% image image, alt or title, credit, "eager", "feature", "grayscale" %}
|
||||
|
||||
<figure class="feature">
|
||||
<img src="{{ image }}" alt="{{ alt or title }}" loading="eager" decoding="sync" class="grayscale">
|
||||
{% if credit %}
|
||||
<figcaption>{{ credit }}</figcaption>
|
||||
{% endif %}
|
||||
</figure>
|
||||
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
{% image image, alt or title, credit, "eager", "feature", "grayscale" %}
|
||||
|
||||
<figure class="feature">
|
||||
<img src="{{ image }}" alt="{{ alt or title }}" loading="eager" decoding="sync" class="grayscale">
|
||||
{% if credit %}
|
||||
<figcaption>{{ credit }}</figcaption>
|
||||
{% endif %}
|
||||
</figure>
|
||||
|
||||
|
||||
More:
|
||||
- https://www.11ty.dev/docs/plugins/image/
|
||||
- https://www.youtube.com/watch?v=e0OHgC677ec
|
||||
- https://www.aleksandrhovhannisyan.com/blog/eleventy-image-transform/
|
||||
- https://coryd.dev/posts/2024/setting-up-image-transforms-in-eleventy
|
||||
- https://coryd.dev/posts/2024/setting-up-image-transforms-in-eleventy
|
||||
|
||||
{%- css "inline" -%}
|
||||
{%- include 'css/table.css' -%}
|
||||
{%- endcss -%}
|
||||
Loading…
Reference in a new issue