Registry / serialization / mdast-util-find-and-replace

mdast-util-find-and-replace

library3.0.2jsnpmunverified

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.

serialization data

npm install mdast-util-find-and-replace

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MDAST-UTIL-FIND-AN

mdast-util-find-and-replace

serializationjavascriptv3.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

findAndReplace

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

✗ const { findAndReplace } = require('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.

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));

Debug

Known issues

breakingVersion 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], …]`.

affects: >=3.0.0

breakingVersion 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.

affects: >=3.0.0

breakingStarting 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.

affects: >=3.0.0

gotchaThe 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.

affects: >=3.0.0

Errors

Common errors & fixes

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.

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`.

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(){...}]]`.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Amazon

Bingbot

Resources

githubhttps://github.com/syntax-tree/mdast-util-find-and-replace ↗

packagehttps://www.npmjs.com/package/mdast-util-find-and-replace ↗

homepagehttps://unifiedjs.com ↗