mdast-util-find-and-replace

What is mdast-util-find-and-replace?

The mdast-util-find-and-replace npm package is a utility for finding and replacing text or patterns in Markdown Abstract Syntax Trees (MDAST). It is particularly useful for manipulating Markdown documents programmatically, allowing developers to automate content updates, apply transformations, and enhance Markdown processing workflows.

What are mdast-util-find-and-replace's main functionalities?

Text Replacement

This feature allows you to replace specific text in the MDAST. In the provided code, 'world' is replaced with 'universe' within the text node of a paragraph.

const u = require('unist-builder');
const findAndReplace = require('mdast-util-find-and-replace');

const tree = u('paragraph', [
  u('text', 'Hello world!')
]);

findAndReplace(tree, {'world': 'universe'});

console.log(tree);

Pattern Replacement with Callback

This feature allows replacing patterns using regular expressions. In the example, occurrences of 'example.com' are turned into clickable links.

const u = require('unist-builder');
const findAndReplace = require('mdast-util-find-and-replace');

const tree = u('paragraph', [
  u('text', 'Visit example.com for more info.')
]);

findAndReplace(tree, /example\.com/g, (match) => {
  return {
    type: 'link',
    url: 'http://example.com',
    children: [{type: 'text', value: match}]
  };
});

console.log(tree);

Other packages similar to mdast-util-find-and-replace

remark-retext

remark-retext is a plugin that bridges between remark (Markdown processor) and retext (natural language processor). While it focuses on natural language processing, it can be used in conjunction with plugins like retext-string-replace to achieve similar find-and-replace functionalities. However, it requires setting up a pipeline with retext, making it less direct than mdast-util-find-and-replace for simple replacements.

unist-util-visit

unist-util-visit is a utility for traversing Unist nodes, which can be used to manually implement find-and-replace functionalities by visiting nodes and modifying them. It offers more control and customization over how nodes are visited and modified compared to mdast-util-find-and-replace, which is more specialized and straightforward for text replacements.

README

mdast-util-find-and-replace

mdast utility to find and replace text in a tree.

Install

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

npm:

npm install mdast-util-find-and-replace

Use

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

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

findAndReplace(tree, 'and', 'or')

findAndReplace(tree, {emphasis: 'em', importance: 'strong'})

findAndReplace(tree, {
  Some: function ($0) {
    return u('link', {url: '//example.com#' + $0}, [u('text', $0)])
  }
})

console.log(inspect(tree))

Yields:

paragraph[8]
├─ link[1] [url="//example.com#Some"]
│  └─ text: "Some"
├─ text: " "
├─ emphasis[1]
│  └─ text: "em"
├─ text: " "
├─ text: "or"
├─ text: " "
├─ strong[1]
│  └─ text: "strong"
└─ text: "."

API

This package exports the following identifiers: findAndReplace. There is no default export.

findAndReplace(tree, find[, replace][, options])

Find and replace text in mdast trees. The algorithm searches the tree in preorder for complete values in Text nodes. Partial matches are not supported.

Signatures

• findAndReplace(tree, find, replace?[, options])
• findAndReplace(tree, search[, options])

Parameters

• tree (Node) — mdast tree
• find (string or RegExp) — Value to find and remove. When string, escaped and made into a global RegExp
• replace (string or Function) — Value to insert. When string, turned into a Text node. When Function, invoked with the results of calling RegExp.exec as arguments, in which case it can return a single or a list of Node, a string (which is wrapped in a Text node), or false to not replace
• search (Object or Array) — Perform multiple find-and-replaces. When Array, each entry is a tuple (Array) of a find (at 0) and replace (at 1). When Object, each key is a find (in string form) and each value is a replace
• options.ignore (Test, default: []) — Any unist-util-is compatible test.

Returns

The given, modified, tree.

Security

Use of mdast-util-find-and-replace does not involve hast or user content so there are no openings for cross-site scripting (XSS) attacks.

Related

• hast-util-find-and-replace — hast utility to find and replace text
• unist-util-select — select unist nodes with CSS-like selectors

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer