satteri-figure

Satteri plugin to transform an image with alt text to a figure with caption. A port of @microflash/rehype-figure to Satteri's HAST plugin API.

[!IMPORTANT] Converting an image with alt text to a figure with caption is an escape hatch. Alt text, title, and captions have different intended purposes, and you should eventually enhance your content to adopt them.

What's this?

This package is a Satteri plugin that takes an image node with alt text (e.g., ![Alt text](path-to-image.jpg)) and converts it to a figure element with caption.

<figure>
  <img src="path-to-image.jpg" alt="Alt text" />
  <figcaption>Alt text</figcaption>
</figure>

Install

npm install satteri-figure
yarn add satteri-figure
pnpm add satteri-figure

Use

Say we have the following module example.js:

import { markdownToHtml } from "satteri";
import satteriFigure from "satteri-figure";

const { html } = markdownToHtml("![Alt text](path-to-image.jpg)", {
  hastPlugins: [satteriFigure()],
});

console.log(html);

Running that with node example.js yields:

<figure><img src="path-to-image.jpg" alt="Alt text"><figcaption>Alt text</figcaption></figure>

API

The default export is satteriFigure, a function returning a HAST plugin definition to pass to hastPlugins.

import satteriFigure, { type SatteriFigureOptions } from "satteri-figure";

const options: SatteriFigureOptions = {
  className: ["figure", "figure--captioned"],
};

const plugin = satteriFigure(options);

Its TypeScript API is:

import type { HastPluginDefinition } from "satteri";

export interface SatteriFigureOptions {
  className?: string | string[];
}

export default function satteriFigure(
  options?: SatteriFigureOptions,
): HastPluginDefinition;

The following options are available. All of them are optional.

• className: class (or list of classes) for the wrapped figure element

By default, no classes are added to the figure element.

Development

From the workspace root:

• Run pnpm build to compile the package to dist/
• Run pnpm typecheck to type-check the implementation, tests, and fixtures
• Run pnpm test to run the behavior tests
• Run pnpm lint to run package lint scripts
• Run pnpm format to run package formatting scripts

License

MIT