rehype-rewrite

What is rehype-rewrite?

The rehype-rewrite package is a plugin for the rehype ecosystem that allows you to rewrite and transform HTML nodes. It provides a way to manipulate the structure and content of HTML documents programmatically.

What are rehype-rewrite's main functionalities?

Rewrite HTML nodes

This feature allows you to rewrite HTML nodes. In this example, all <a> tags are transformed into <span> tags.

const rehype = require('rehype');
const rehypeRewrite = require('rehype-rewrite');

rehype()
  .use(rehypeRewrite, {
    rewrite: (node, index, parent) => {
      if (node.tagName === 'a') {
        node.tagName = 'span';
      }
    }
  })
  .process('<a href="#">Link</a>', (err, file) => {
    if (err) throw err;
    console.log(String(file));
  });

Modify text content

This feature allows you to modify the text content within HTML nodes. In this example, any text containing 'Hello' is replaced with 'Hi'.

const rehype = require('rehype');
const rehypeRewrite = require('rehype-rewrite');

rehype()
  .use(rehypeRewrite, {
    rewrite: (node, index, parent) => {
      if (node.type === 'text' && node.value.includes('Hello')) {
        node.value = node.value.replace('Hello', 'Hi');
      }
    }
  })
  .process('<p>Hello World</p>', (err, file) => {
    if (err) throw err;
    console.log(String(file));
  });

Add attributes to elements

This feature allows you to add attributes to HTML elements. In this example, an 'alt' attribute is added to all <img> tags.

const rehype = require('rehype');
const rehypeRewrite = require('rehype-rewrite');

rehype()
  .use(rehypeRewrite, {
    rewrite: (node, index, parent) => {
      if (node.tagName === 'img') {
        node.properties = node.properties || {};
        node.properties.alt = 'An image';
      }
    }
  })
  .process('<img src="image.png" />', (err, file) => {
    if (err) throw err;
    console.log(String(file));
  });

Other packages similar to rehype-rewrite

rehype-parse

rehype-parse is a plugin for parsing HTML into a syntax tree. While it does not provide rewriting capabilities, it is often used in conjunction with other rehype plugins to manipulate HTML.

rehype-stringify

rehype-stringify is a plugin for serializing a syntax tree back into HTML. It is typically used after parsing and transforming the HTML with other rehype plugins.

hast-util-select

hast-util-select is a utility for selecting nodes in a HAST (Hypertext Abstract Syntax Tree). It can be used to find and manipulate specific nodes, similar to how rehype-rewrite allows for node transformations.

README

rehype-rewrite

Rewrite element with rehype.

Installation

This package is ESM only: Node 12+ is needed to use it and it must be import instead of require.

npm install rehype-rewrite

Usage

🚧 Migrate from rehype-rewrite v2.x to v3.x.

rehype()
- .use(rehypeRewrite, (node, index, parent) => {})
+ .use(rehypeRewrite, {
+   rewrite: (node, index, parent) => {}
+ })

import { rehype } from 'rehype';
import rehypeRewrite from 'rehype-rewrite';
import stringify from 'rehype-stringify';

const html = `<h1>header</h1>`;
const htmlStr = rehype()
  .data('settings', { fragment: true })
  .use(rehypeRewrite, {
    rewrite: (node, index, parent) => {
      if(node.type == 'text' && node.value == 'header') {
        node.value = ''
      }
    }
  })
  .use(stringify)
  .processSync(html)
  .toString()

<h1>header</h1>

Output:

<h1></h1>

Options

import { Plugin } from 'unified';
import { Root, Element, ElementContent, RootContent } from 'hast';
/** Get the node tree source code string */
export declare const getCodeString: (data?: ElementContent[], code?: string) => string;
export declare type RehypeRewriteOptions = {
  /**
   * Select an element to be wrapped. Expects a string selector that can be passed to hast-util-select ([supported selectors](https://github.com/syntax-tree/hast-util-select/blob/master/readme.md#support)).
   * If `selector` is not set then wrap will check for a body all elements.
   */
  selector?: string;
  /** Rewrite Element. */
  rewrite(node: Root | RootContent, index: number | null, parent: Root | Element | null): void;
};
declare const remarkRewrite: Plugin<[RehypeRewriteOptions?], Root>;
export default remarkRewrite;

selector?: string;

Select an element to be wrapped. Expects a string selector that can be passed to hast-util-select (supported selectors). If selector is not set then wrap will check for a body all elements.

rewrite(node, index, parent): void;

Rewrite element.

Example

Example 1

import { rehype } from 'rehype';
import rehypeRewrite from 'rehype-rewrite';
import stringify from 'rehype-stringify';

const html = `<h1>header</h1><h1>header</h1><h1 class="title3">header</h1>`;
const htmlStr = rehype()
  .data('settings', { fragment: true })
  .use(rehypeRewrite, {
    selector: 'h1',
    rewrite: (node) => {
      if (node.type === 'element') {
        node.properties.className = 'test';
      }
    }
  })
  .use(stringify)
  .processSync(html)
  .toString()

<h1>header</h1>
<h1>header</h1>
<h1 class="title3">header</h1>

Output:

<h1 class="test">header</h1>
<h1 class="test">header</h1>
<h1 class="test">header</h1>

Example 2

import { rehype } from 'rehype';
import rehypeRewrite from 'rehype-rewrite';
import stringify from 'rehype-stringify';

const html = `<h1>header</h1>`;
const htmlStr = rehype()
  .use(rehypeRewrite, {
    rewrite: (node) => {
      if (node.type == 'element' && node.tagName == 'body') {
        node.properties = { ...node.properties, style: 'color:red;'}
      }
    }
  })
  .use(stringify)
  .processSync(html)
  .toString()

<h1>header</h1>

Output:

<html><head></head><body style="color:red;"><h1>header</h1></body></html>

Example 3

import { rehype } from 'rehype';
import rehypeRewrite from 'rehype-rewrite';
import stringify from 'rehype-stringify';

const html = `<h1>hello</h1>`;
const htmlStr = rehype()
  .data('settings', { fragment: true })
  .use(rehypeRewrite, {
    rewrite: (node) => {
      if (node.type == 'element' && node.tagName == 'h1') {
        node.children = [ ...node.children, {
          type: 'element',
          tagName: 'span',
          properties: {},
          children: [
            {type: 'text', value: ' world'}
          ]
        }]
      }
    }
  })
  .use(stringify)
  .processSync(html)
  .toString()

<h1>hello</h1>

Output:

<h1>hello<span> world</span></h1>

Example 4

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import rehypeRaw from 'rehype-raw';
import remark2rehype from 'remark-rehype';
import rehypeRewrite from 'rehype-rewrite';
import stringify from 'rehype-stringify';

const html = `<h1>hello</h1>`;
const htmlStr = unified()
  .use(remarkParse)
  .use(remark2rehype, { allowDangerousHtml: true })
  .use(rehypeRaw)
  .use(rehypeRewrite, {
    rewrite: (node) => {
      if (node.type == 'element' && node.tagName == 'h1') {
        node.properties = { ...node.properties, style: 'color:red;' }
      }
    }
  })
  .use(stringify)
  .processSync(html)
  .toString()

<h1>hello</h1>

Output:

<h1 style="color:red;">Hello World!</h1>

Related

• rehype-video Add improved video syntax: links to .mp4 and .mov turn into videos.
• rehype-attr New syntax to add attributes to Markdown.
• rehype-ignore Ignore content display via HTML comments, Shown in GitHub readme, excluded in HTML.
• rehypejs HTML processor powered by plugins part of the @unifiedjs collective
• remark-parse remark plugin to parse Markdown
• remark-rehype remark plugin to transform to rehype
• rehype-raw rehype plugin to reparse the tree (and raw nodes)
• rehype-stringify rehype plugin to serialize HTML

Contributors

As always, thanks to our amazing contributors!

Made with action-contributors.

License

MIT © Kenny Wong