diff options
| author | Dennis Fink | 2026-11-11 19:57:38 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-11 19:57:38 +0100 |
| commit | e6215f84bf2cab0bbd8bb0a42ddae0ee6de3cfd6 (patch) | |
| tree | 83910d7fee66d210464318bc7ad568c713e25e2d /packages/responsive-image/README.md | |
| parent | 8963ed31ce537a736ddba99baf68b31858b319b8 (diff) | |
| download | dennisfink.me-main.tar.gz dennisfink.me-main.zip | |
This adds the responsive-image plugin directly to the project, including
its source code, documentation, and tests, allowing it to be maintained
locally.
It also configures responsive image sizes, updates gallery images to use
srcset, and preserves original image URLs for full-resolution viewing.
Markdown images gain lazy loading while retaining compatibility with the
existing image viewer.
Diffstat (limited to 'packages/responsive-image/README.md')
| -rw-r--r-- | packages/responsive-image/README.md | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/packages/responsive-image/README.md b/packages/responsive-image/README.md new file mode 100644 index 0000000..8864df2 --- /dev/null +++ b/packages/responsive-image/README.md @@ -0,0 +1,86 @@ +# Lektor Responsive Images Plugin + +[](https://pypi.org/project/lektor-responsive-image/) +[](https://pypi.python.org/pypi/lektor-responsive-image/) +[](https://github.com/dairiki/lektor-responsive-image/blob/master/LICENSE) +[](https://github.com/dairiki/lektor-responsive-image/actions) +[](https://trackgit.com) + +This plugin hacks up Lektor’s Markdown renderer to support +multi-resolution responsive images in Markdown text. + +Local images will be resized to a variety of sizes, and `<img>` tags +will be rendered with `srcset` and (optionally) `sizes` attributes in +order to support the use of [responsive image +resolutions][mdn-responsive-images]. + +This plugin also registers a Jinja global function, `responsive_image`, +which can be used to render markup for multi-resolution images from +Jinja templates. + +[mdn-responsive-images]: <https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images> + "MDN: Responsive Images" + +## Configuration + +The plugin is configured through `configs/responsive-images.ini`. +Here is an annotated example: + +```ini +# Currently, only a section named "default" is used +[default] + +# Widths of images to generate. +# +# Images will be generated at these widths (but only up to the native +# width of the image.) +# +# (This is the default value.) +widths = 480 800 1200 2400 + +# Image quality for generating scaled images +# (This is the default value.) +# NOTE: the quality parameter will be ignored if running under lektor version +# before 3.1. +quality = 92 + +# Width of the image put into the `src` attribute of the `<img>` tag. +# (Though the orignal image is never up-scaled. If the original is narrower than +# this width, then the original image is used.) +# (This is the default value.) +default_width = 1200 + +# Value put into the `sizes` attribute of the `<img>` tag. +# The default is not to set a `sizes` attribute +sizes = (max-width: 576px) 95vw, (max-width: 992px) 65vw, 800px +``` + +## Usage + +In the common use case, you will want to adjust the CSS stylesheet for +your site so that images within Markdown text get either `display: +block` or `display: inline-block`, along with `max-width: 100%`, or +similar. + +## Jinja global function + +This plugin also registers a Jinja global function named `responsive_image`. +It expects a single argument, which should be an `Image` instance. +It returns an object which has an `.attr` attribute whose value is +a dict of attribute which could be set on an `<img>` tag to generate +markup for a multi-resolution image. E.g. + +```html+jinja +{% set image = this.attachments.get('figure.png') %} +{% set img_attrs = responsive_image(image).attrs %} +<figure class="figure"> + <img class="figure-img" {{ img_attrs|xmlattr }}> + <figcaption class="figure-caption text-center"> + {{- this.caption -}} + </figcaption> +</figure> +``` + +## Author + +Jeff Dairiki <dairiki@dairiki.org> |
