A markdown-it plugin to set aspect-ratio of responsive images, make them lazy loading, and to make videos responsive.
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 is around the corner and will help solving the CLS problem for responsive images.
The markdown-it-fitmedia plugin makes use of
aspect-ratio by analyzing each of your referenced images, determining its dimensions, and setting the
aspect-ratio based on the dimensions of the image. By default, the plugin will also add the
loading="lazy" html attribute to your images. Example:
Also, html inside of your markdown, like for example
will be transformed into
Wrapping media #
markdown-it-fitmedia carries an adoption of the original fit-vids script to make
video tags responsive. Embedded videos are not automatically responsive or fluid. They come with a fixed setting for width and height. To make them responsive while keeping aspect ratio, they are embedded into a wrapper element. The wrapper receives some clever padding and positioning, and as a last step the fixed dimensions are removed from the video. The technique has been described by Thierry Koblentz in his A List Apart article “Creating Intrinsic Ratios for Video” in 2009. For example, this
imgDir, default is
'': Define the directory where images are stored. The given string will be prepended to the
srcpath 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
/contentand images are stored in
/content/img. During buildtime the images are getting copied into the destination location, where
/contentwill 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 configuring
lazyLoad, default is
true, images will receive the html attribute-setting of
aspectRatio, default is
true, the CSS property
aspect-ratiois set on images and wrapped media.
fitWrapElements, default is
['iframe', 'video']: Define the html tags to be put into a responsive wrapper.