unified

unified is a core package used to process content with plugins. It works with content as structured data (Abstract Syntax Trees or ASTs).

It is part of a larger ecosystem of 500+ packages, including specialized ecosystems like:

• remark: for Markdown
• rehype: for HTML
• retext: for natural language

Use unified when you need to connect different types of content (e.g., converting Markdown to HTML) by picking and choosing specific plugins from these ecosystems.

The unified ecosystem processes content using syntax trees through a three-step pipeline:

1. Parse: A parser converts raw text into a syntax tree.
2. Run: Plugins (transformers) inspect and modify the syntax tree.
3. Stringify: A compiler converts the modified syntax tree back into text.

A processor orchestrates this entire flow. On its own, the root unified() processor does nothing; it must be configured with plugins to perform specific tasks like parsing markdown or compiling HTML.

When combining different syntax tree ecosystems (e.g., markdown to HTML), you can use two modes of transformation:

• Bridge mode: Transforms the tree from an origin format to a destination format. A different processor runs on the destination tree, but the original processor continues working on the origin tree after the transformation is complete.
• Mutate mode: Transforms the syntax tree from one format to another, but the original processor continues transforming the destination tree, effectively discarding the origin tree.

Common plugins for these transformations include:

• remark-retext: Markdown $\rightarrow$ Natural Language
• remark-rehype: Markdown $\rightarrow$ HTML
• rehype-retext: HTML $\rightarrow$ Natural Language
• rehype-remark: HTML $\rightarrow$ Markdown

The unified package is ESM only. Install it based on your environment:

Node.js (version 16+): Use npm to install the package.

Deno: Import directly from esm.sh.

Browsers: Import via a module script using esm.sh with the ?bundle query parameter.

npm install unified

To create a functional processor, use the .use() method to chain plugins. Each plugin can perform parsing, transformation, or compilation.

Example of a pipeline that parses markdown, converts it to HTML, adds a document title, formats the HTML, and then stringifies it to a string:

const processor = unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeDocument, {title: '👋🌍'})
  .use(rehypeFormat)
  .use(rehypeStringify)

Converts text (string or VFile) into a syntax tree. This method performs the parse phase and automatically freezes the processor if it is not already frozen.

import remarkParse from 'remark-parse'
import {unified} from 'unified'

const tree = unified().use(remarkParse).parse('# Hello world!')

console.log(tree)

Compiles a syntax tree into its textual representation (typically a string or Uint8Array). This performs the stringify phase. This method freezes the processor if it is not already frozen.

import {h} from 'hastscript'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'

const tree = h('h1', 'Hello world!')

const document = unified().use(rehypeStringify).stringify(tree)

console.log(document)

Use processor.data() to store information in an object that is accessible to all plugins in the processor. This is useful for sharing configuration (like a list of self-closing HTML elements) across multiple plugins.

Signatures:

• processor = processor.data(key, value) (Set a value)
• processor = processor.data(dataset) (Set a whole dataset)
• value = processor.data(key) (Get a value)
• dataset = processor.data() (Get the entire dataset)

Note: You cannot set data on a frozen processor. Call the processor first to create a new unfrozen instance.

import {unified} from 'unified'

const processor = unified().data('alpha', 'bravo')

processor.data('alpha') // => 'bravo'
processor.data() // => {alpha: 'bravo'}

processor.data({charlie: 'delta'})
processor.data() // => {charlie: 'delta'}

A frozen processor is meant to be extended and not configured directly. Once frozen, it cannot be unfrozen. To use a frozen processor, you must call it to create a new unfrozen instance.

Processors freeze automatically when calling .parse(), .run(), .runSync(), .stringify(), .process(), or .processSync().

import rehypeParse from 'rehype-parse'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'

// Create a frozen base processor
export const rehype = unified().use(rehypeParse).use(rehypeStringify).freeze()

// Use it by calling it to get a new unfrozen processor
import rehypeFormat from 'rehype-format'
rehype()
  .use(rehypeFormat)