Skip to content

Latest commit

 

History

History
91 lines (71 loc) · 4.58 KB

README.md

File metadata and controls

91 lines (71 loc) · 4.58 KB
Raw

rehype-semantic-images

test workflow codecov NPM Version

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