@ljoss/rehype-figure-caption

Transform your images into semantic and accessible <figure> elements with optional <figcaption> using this Rehype plugin. It handles images in both Markdown and raw HTML, enhancing your content's structure and presentation.

Installation

Install the plugin and its required dependencies:

Using npm:

npm install @ljoss/rehype-figure-caption unified remark-parse remark-rehype rehype-raw rehype-stringify unist-util-visit-parents

Using Yarn:

yarn add @ljoss/rehype-figure-caption unified remark-parse remark-rehype rehype-raw rehype-stringify unist-util-visit-parents

Note: This plugin operates at the Rehype (HTML) level and depends on the following packages:

• unified: Core of the Unified framework.
• remark-parse: Parses Markdown to MDAST (Markdown Abstract Syntax Tree).
• remark-rehype: Converts MDAST to HAST (HTML Abstract Syntax Tree).
• rehype-raw: Parses raw HTML within Markdown (needed if you have raw HTML).
• rehype-stringify: Serializes HAST to HTML.
• unist-util-visit-parents: Utility for traversing the syntax tree with access to parent nodes.

Usage

Integrate the plugin into your Unified processing pipeline.

Example: Converting Markdown to HTML

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkRehype from 'remark-rehype';
import rehypeRaw from 'rehype-raw'; // Needed if processing raw HTML
import rehypeStringify from 'rehype-stringify';
import rehypeFigureCaption from '@ljoss/rehype-figure-caption';

const processor = unified()
  .use(remarkParse) // Parses Markdown to MDAST
  .use(remarkRehype, { allowDangerousHtml: true }) // Converts MDAST to HAST, allows raw HTML
  .use(rehypeRaw) // Parses raw HTML in Markdown to HAST
  .use(rehypeFigureCaption, {
    figureClassName: 'custom-figure',
    imageClassName: 'custom-image',
    captionClassName: 'custom-caption',
    allowEmptyCaption: true, // Wraps images without alt text
  })
  .use(rehypeStringify); // Converts HAST to HTML

const markdown = `
![Alt Text](path-to-image.jpg)

<img src="path-to-image.jpg" alt="Alt Text" class="test">

![](path-to-image.jpg)

Some text before ![Image in text](image-in-text.jpg) some text after.

<p>Some text and <img src="inline-image.jpg" alt="Inline Image"> more text.</p>
`;

processor.process(markdown).then((file) => {
  console.log(String(file));
});

Expected Output

<figure class="custom-figure">
  <img src="path-to-image.jpg" alt="Alt Text" class="custom-image">
  <figcaption class="custom-caption">Alt Text</figcaption>
</figure>

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

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

<p>Some text before </p>
<figure>
  <img src="image-in-text.jpg" alt="Image in text">
  <figcaption>Image in text</figcaption>
</figure>
<p> some text after.</p>

<p>Some text and </p>
<figure>
  <img src="inline-image.jpg" alt="Inline Image">
  <figcaption>Inline Image</figcaption>
</figure>
<p> more text.</p>

Simplified Usage Without Raw HTML

If your Markdown content does not contain raw HTML, you can omit rehype-raw and the allowDangerousHtml option:

const processor = unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeFigureCaption)
  .use(rehypeStringify);

Options

Customize the plugin's behavior using the following options:

| Option | Type | Description | Default | | ------------------- | --------- | ----------------------------------------------------------------------------- | ----------- | | figureClassName | string | CSS class to add to <figure> elements | undefined | | imageClassName | string | CSS class to add to <img> elements | undefined | | captionClassName | string | CSS class to add to <figcaption> elements | undefined | | allowEmptyCaption | boolean | If true, wraps images without alt text in <figure> without <figcaption> | false |

Processing Flow

The plugin processes your content through the following steps:

1. Traverse the Syntax Tree: The plugin visits each node in the HTML syntax tree (HAST), specifically looking for <img> elements.

2. Skip Images Inside Links: If an image is inside an <a> tag, it is skipped to avoid breaking the link structure.

3. Check Alt Text: The plugin checks the alt attribute of the image.

   • If alt text exists, or allowEmptyCaption is true, it proceeds.
   • Otherwise, the image is left unaltered.

4. Add Class Names: If provided in the options, class names are added to the <img>, <figure>, and <figcaption> elements.

5. Create <figure> and <figcaption> Elements:

   • A <figure> element is created to wrap the image.
   • If alt text exists, a <figcaption> element is created with the alt text as its content.

6. Replace or Restructure Nodes:

   • If the parent is a <p> element:

     • With only the <img>: The <p> is replaced with the <figure>.
     • With additional content: The <p> is split into separate nodes before and after the <img>.
       • Content before the image remains in a <p>.
       • The <figure> is inserted after.
       • Content after the image is placed in a new <p>.

   • If the parent is not a <p> element:

     • The <img> is replaced with the <figure>.

7. Result: The syntax tree is updated, and when stringified, produces HTML with images wrapped in <figure> elements and captions added where appropriate.

Contributing

We welcome contributions!

Development Setup

1. Clone the repository

   git clone https://github.com/Ljoss-Studios/rehype-figure-caption.git

2. Navigate to the project directory

   cd rehype-figure-caption

3. Install dependencies

   Using npm:

   npm install

   Using Yarn:

   yarn install

4. Run tests

   Using npm:

   npm test

   Using Yarn:

   yarn test

5. Start development server (if applicable)

   If the project has a development server or watch mode:

   npm run dev

   Or with Yarn:

   yarn dev

Submitting Changes

• Fork the repository and create a new branch.
• Write tests to cover your changes.
• Ensure all tests pass before submitting.
• Submit a pull request detailing your changes.

License

This project is licensed under the MIT License.

Thank you for your interest and contributions!

Important Notes

• Dependency on Rehype: This plugin operates at the Rehype level, manipulating the HTML syntax tree (HAST). It requires remark-rehype to convert Markdown to HTML and rehype-raw to parse any raw HTML within your Markdown content.

• Processing Pipeline: Ensure your processing pipeline includes the necessary steps:

  1. Parse Markdown to MDAST: Using remark-parse.
  2. Convert MDAST to HAST: Using remark-rehype.
     • Set allowDangerousHtml: true if processing raw HTML.
  3. Parse Raw HTML to HAST Nodes: Using rehype-raw (if needed).
  4. Apply rehype-figure-caption Plugin: To transform images.
  5. Stringify HAST to HTML: Using rehype-stringify.

• Raw HTML Support: Include rehype-raw in your pipeline to process raw HTML <img> elements embedded in your Markdown.

Frequently Asked Questions

Q1: Can I use this plugin with Remark directly?

A: No, this plugin is designed to work with Rehype, not Remark. It manipulates the HTML AST (HAST), which is available after converting Markdown to HTML using remark-rehype.

Q2: What if I only have Markdown images and no raw HTML?

A: Even if your content only contains Markdown images, you can still use this plugin. Just ensure your pipeline includes remark-rehype to convert the Markdown to HTML before applying the plugin.

Q3: Do I need to set allowDangerousHtml: true if I don't have raw HTML in my Markdown?

A: No, if your Markdown does not contain raw HTML, you can omit the allowDangerousHtml: true option and the rehype-raw plugin.

Acknowledgments

We thank all contributors and users who have provided feedback and suggestions to improve this plugin.

For any questions or suggestions, feel free to open an issue on the GitHub repository or contact us directly.