mdast Find and Replace Utility

3.0.2 · active · verified Sun Apr 19

mdast-util-find-and-replace is a utility within the unifiedjs ecosystem designed to find patterns (strings or regular expressions) within the text nodes of an mdast (Markdown Abstract Syntax Tree) and replace them with new mdast nodes. The current stable version is 3.0.2. It typically receives updates for bug fixes and minor enhancements, with major versions introducing breaking changes less frequently, as seen with the transition to v3.0.0. Key differentiators include its tight integration with the mdast specification, its ability to produce complex node structures as replacements, and its focus on efficient, preorder traversal. It's particularly useful for transforming markdown content programmatically, such as converting specific text patterns into links, mentions, or other AST elements.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module [path] from [path] not supported. Instead change the require of index.js to a dynamic import() which is also supported.
```
cause Attempting to `require()` `mdast-util-find-and-replace` in a CommonJS module after upgrading to v3.x.

fix Change `const { findAndReplace } = require('mdast-util-find-and-replace')` to `import { findAndReplace } from 'mdast-util-find-and-replace'` and ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json`).
```
TypeError: `list` must be a list of tuples or a tuple. Got `object`.
```
cause Using the old `{ find: replace }` object format for replacement rules after upgrading to v3.x.

fix Convert your replacement object to an array of tuples: `[[/pattern/g, 'replacement'], ['string', function(){...}]]`.

Warnings

breaking Version 3.0.0 changed the API to accept find-and-replace pairs only as `[find, replace]` tuples or an `Array<[find, replace]>`. The old `{find: replace}` object syntax is no longer supported.
Fix: Update your `list` argument: `find, replace` becomes `[find, replace]`, and `{find: replace, …}` becomes `[[find, replace], …]`.
breaking Version 3.0.0 requires Node.js 16 or higher due to a shift to modern JavaScript features and module resolution.
Fix: Ensure your Node.js environment is at least version 16.0.0. Update your runtime if necessary.
breaking Starting with version 3.0.0, `findAndReplace` now returns `undefined` instead of the modified tree. The function modifies the tree in place.
Fix: Remove any code that expects a return value from `findAndReplace`. The `tree` object passed as the first argument is modified directly.
gotcha The package is ESM-only since v3.0.0, which means it can only be `import`ed and cannot be `require`d in CommonJS modules. This might cause issues in older Node.js projects or mixed environments.
Fix: Migrate your project to use ES modules (`import`/`export`) or use dynamic `import()` if you must `require` ESM packages from CommonJS. Alternatively, stick to `mdast-util-find-and-replace` v2 for CommonJS compatibility.

Install

npm install mdast-util-find-and-replace npm
yarn add mdast-util-find-and-replace yarn
pnpm add mdast-util-find-and-replace pnpm

Imports

findAndReplace

wrong:

const { findAndReplace } = require('mdast-util-find-and-replace')

correct:

import { findAndReplace } from 'mdast-util-find-and-replace'

mdast-util-find-and-replace is ESM-only since version 3.0.0, requiring Node.js 16+.

FindAndReplaceTuple

import type { FindAndReplaceTuple } from 'mdast-util-find-and-replace'

TypeScript type for a single find-and-replace pair.

ReplaceFunction
```
import type { ReplaceFunction } from 'mdast-util-find-and-replace'
```
TypeScript type for a function that returns replacement nodes.

Quickstart

This example demonstrates how to import `findAndReplace`, construct an mdast tree using `unist-builder`, and then apply multiple find-and-replace operations, including string, regex, and function-based replacements, before inspecting the modified tree.

import {findAndReplace} from 'mdast-util-find-and-replace';
import {u} from 'unist-builder';
import {inspect} from 'unist-util-inspect';

const tree = u('paragraph', [
  u('text', 'Some '),
  u('emphasis', [u('text', 'emphasis')]),
  u('text', ' and '),
  u('strong', [u('text', 'importance')]),
  u('text', '.')
]);

findAndReplace(tree, [
  [/and/gi, 'or'],
  [/emphasis/gi, 'em'],
  [/importance/gi, 'strong'],
  [
    /Some/g,
    function ($0) {
      return u('link', {url: '//example.com#' + $0}, [u('text', $0)]);
    }
  ]
]);

console.log(inspect(tree));

view raw JSON →