markdown-it-fitmedia
v1.0.2
Published
A markdown-it plugin to set aspect-ratio of responsive images, videos, and iframes
Downloads
70
Maintainers
Readme
A markdown-it plugin to set aspect-ratio of responsive images, make images lazy loading, and to make videos responsive. The original idea goes back to FitVids.js and the evolutionary improvements that were possible because browsers improved.
Images
Responsive images can create cumulative layout shifts (CLS) when loaded, because it´s difficult to get their height correct when their width is flexible. Check "Setting Height And Width On Images Is Important Again" to get a comprehensive view about the problem. The CSS property aspect-ratio
has now a global availability of 94.32 % and will help solving the CLS problem for responsive images.
The markdown-it-fitmedia plugin will analyze each of your referenced images, determine its dimensions, and set (or expand) the html style
attribute of the image with the aspect-ratio
property based on the dimensions of the image. By default, the plugin will also add the loading="lazy"
html attribute to your images and will set the html attributers width
and height
with the correct image dimensions to give the browser a hint of the image size.
Example:
![Image of Spitfire tool](/img/spitfire/spitfire.jpg)
will become
<img
alt="Image of Spitfire tool"
src="/img/spitfire/spitfire.jpg"
loading="lazy"
style="aspect-ratio:750/388;"
width="750"
height="388"
/>
Also, html in your markdown, like for example
<figure>
<img alt="" src="/img/spitfire/spitfire.jpg" />
<figcaption>Image of Spitfire tool</figcaption>
</figure>
will be transformed into
<figure>
<img
alt=""
src="/img/spitfire/spitfire.jpg"
loading="lazy"
style="aspect-ratio:750/388;"
width="750"
height="388"
/>
<figcaption>Image of Spitfire tool</figcaption>
</figure>
Fitting media
Embedded videos and iframes are not automatically responsive or fluid. They come with a fixed setting for width and height. To make them responsive while keeping aspect ratio, markdown-it-fitmedia will set set (or expand) the style
attribute of these elements with the aspect-ratio
property, based on the given width and height. Also added to the style
will be width:100%; max-width:100%; height:auto;
.
The clever padding solution that has been used in the passed, as described by Thierry Koblentz in Creating Intrinsic Ratios for Video, is no longer required, because browsers improved over time and do support the aspect-ratio
now well.
[!IMPORTANT] The fitting of media, like described here, can only be performed for elements that have the html attributes
width
andheight
set!
For example, this
<iframe
src="https://player.vimeo.com/video/304626830"
width="600"
height="338"
></iframe>
will become
<iframe
src="https://player.vimeo.com/video/304626830"
style="aspect-ratio:600/338; width:100%; max-width:100%; height:auto;"
width="600"
height="338"
>
</iframe>
Usage
var markdownIt = require("markdown-it");
var markdownItFitMedia = require("markdown-it-fitmedia");
markdownIt({
html: true,
}).use(markdownItFitMedia, {
//default options, you can omit these
imgDir: "",
imgLazyLoad: true,
imgDecoding: "auto",
fitElements: ["iframe", "video"],
});
Configuration
imgDir
, default is''
: Define the directory where images are stored. The given string will be prepended to thesrc
path of the images you are using in your markdown to load and analyze an image for dimension detection. Example use case: I´m using this plugin during buildtime for my 11ty powered blog. There I have a source directory and a destination directory for the created site. The source directory is/content
and images are stored in/content/img
. During buildtime the images are getting copied into the destination location, where the/content
part of the path will be removed, so that the resulting images can be referenced in the html with/img/…
. However, markdow-it-fitmedia needs to access the images in the source directory, therefore, in this case, I´m configuringimgDir: './content'
.imgLazyLoad
orlazyLoad
, default istrue
: Whentrue
, images will receive the html attribute-setting ofloading="lazy"
.imgDecoding
ordecoding
, default is'auto'
: If other thanauto
, will set the value of thedecoding
html attribute with that value.fitElements
, default is['iframe', 'video']
: Define the html tags to be fitted (you do not need to haveimg
in this list, because images are fitted anyway)