rehype-semantic-images

This plugin enhances images in HTML documents processed by rehype in the unified ecosystem. It adds semantic elements such as figure, figcaption, and customizable container elements, and supports lazy loading options, custom class names, and IDs. It enables dynamic source set and URL building, which allows developers to improve accessibility, SEO, and performance of web pages. With fine-grained control over image presentation and loading behavior, this plugin provides developers with greater flexibility and customization options.

Install

npm i -D @benjc/rehype-semantic-images

Usage

import rehypeSemanticImages from "@benjc/rehype-semantic-images";
import rehype from "rehype";
import rehypeParse from "rehype-parse";
import { unified } from "unified";

unified()
  .use(rehypeParse, { fragment: true })
  .use(rehypeSemanticImages)
  .process(`<img src="image.jpg" alt="My alt text" />`);

// Or with options:
unified()
  .use(rehypeParse, { fragment: true })
  .use(rehypeSemanticImages, {
    urlBuilder: (src) => `https://my-cdn.com/${src}`,
  })
  .process(`<img src="image.jpg" alt="My alt text" />`);

Input

<img src="image.jpg" alt="My alt text" />

Output

<figure class="rsi-figure">
  <div class="rsi-container">
    <img class="rsi-image" alt="My alt text" loading="lazy" sizes="100vw" src="image.jpg" srcset="image.jpg 1x" />
  </div>
  <figcaption class="rsi-figcaption">My alt text</figcaption>
</figure>

Options

Option	Type	Description
urlBuilder	Function	A function that takes the src of an image and returns a new src.
disableLazy	Boolean	If true, the loading attribute of the img element will be set to "eager". Otherwise, it will be set to "lazy".
defaultSizes	String	The value for the sizes attribute of the img element.
elements.img	Object	An object containing additional properties for the img element.
elements.container	Object	An object containing properties for the div container element. If disable is true, the container will not be added.
elements.figcaption	Object	An object containing properties for the figcaption element. If disable is true, the figcaption will not be added.
elements.figure	Object	An object containing properties for the figure element. If disable is true, the figure will not be added.
srcSetSteps	Array of numbers	An array of multipliers for generating the srcSet attribute of the img element. If not provided or empty, only the original src will be used.

These options can be passed to the rehype-semantic-images plugin as part of the options object. For example:

rehypeSemanticImages({
  defaultSizes: "(min-width: 960px) 720px, 100vw",
  disableLazy: false,
  elements: {
    container: { className: "custom-container", id: "containerID", disable: false },
    figcaption: { className: "custom-figcaption", id: "figcaptionID", disable: false },
    figure: { className: "custom-figure", id: "figureID", disable: false },
    img: { className: "custom-image", id: "imageID" },
  },
  srcSetSteps: [1, 2, 3],
  urlBuilder: (src) => `https://my-cdn.com/${src}`,
});

This will customize the top and bottom links according to the provided options.

License

MIT © benjamincharity