unified

☔️ interface for parsing, inspecting, transforming, and serializing content through syntax trees

4,445

108

4,445

View on GitHub View on NPM

Top Related Projects

remark

7,533

markdown processor powered by plugins part of the @unifiedjs collective

marked

32,981

A markdown parser and compiler. Built for speed.

markdown-it

18,123

Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed

Markdown parser, done right. Commonmark support, extensions, syntax plugins, high speed - all in one. Gulp and metalsmith plugins available. Used by Facebook, Docusaurus and many others! Use https://github.com/breakdance/breakdance for HTML-to-markdown conversion. Use https://github.com/jonschlinkert/markdown-toc to generate a table of contents.

showdown

14,258

A bidirectional Markdown to HTML to Markdown converter written in Javascript

commonmark.js

1,436

CommonMark parser and renderer in JavaScript

Quick Overview

Unified is a powerful ecosystem of tools for parsing, inspecting, transforming, and serializing content through syntax trees. It provides a pluggable system for working with various formats, including Markdown, HTML, and natural language, allowing developers to build complex content processing pipelines with ease.

Pros

Highly modular and extensible architecture
Supports a wide range of content formats
Large ecosystem of plugins and tools
Well-documented and actively maintained

Cons

Steep learning curve for beginners
Can be complex to set up for advanced use cases
Performance may be impacted when processing large documents
Some plugins may have inconsistent documentation

Code Examples

Parsing and stringifying Markdown:

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

const processor = unified()
  .use(remarkParse)
  .use(remarkStringify)

const result = await processor.process('# Hello, world!')
console.log(String(result))

Converting Markdown to HTML:

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'

const processor = unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeStringify)

const result = await processor.process('# Hello, world!')
console.log(String(result))

Adding a custom plugin:

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

function myPlugin() {
  return (tree) => {
    // Modify the syntax tree here
    tree.children.push({
      type: 'paragraph',
      children: [{ type: 'text', value: 'Added by my plugin' }]
    })
  }
}

const processor = unified()
  .use(remarkParse)
  .use(myPlugin)
  .use(remarkStringify)

const result = await processor.process('# Original content')
console.log(String(result))

Getting Started

To get started with Unified, follow these steps:

Install the necessary packages:

npm install unified remark-parse remark-stringify

Create a basic processor:

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

const processor = unified()
  .use(remarkParse)
  .use(remarkStringify)

const result = await processor.process('# Hello, Unified!')
console.log(String(result))

Run the script and see the processed output.

For more advanced usage and additional plugins, refer to the Unified documentation and explore the ecosystem of available packages.

Competitor Comparisons

remark

7,533

markdown processor powered by plugins part of the @unifiedjs collective

Pros of remark

Specialized for Markdown processing, offering a more focused and optimized solution
Extensive ecosystem of plugins specifically tailored for Markdown manipulation
Simpler learning curve for developers primarily working with Markdown

Cons of remark

Limited to Markdown processing, less versatile for other content types
Potentially overwhelming number of plugins for newcomers
May require additional setup for non-Markdown tasks

Code Comparison

remark:

import { remark } from 'remark';
import html from 'remark-html';

const result = await remark()
  .use(html)
  .process('# Hello, world!');

unified:

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkHtml from 'remark-html';

const result = await unified()
  .use(remarkParse)
  .use(remarkHtml)
  .process('# Hello, world!');

Summary

remark is a specialized tool for Markdown processing, offering a rich ecosystem of plugins and a simpler learning curve for Markdown-focused tasks. However, it's limited to Markdown and may require additional setup for other content types. unified, on the other hand, provides a more versatile foundation for various content processing tasks, including Markdown, but may have a steeper learning curve and require more configuration for specific use cases.

marked

32,981

A markdown parser and compiler. Built for speed.

Pros of marked

Lightweight and fast Markdown parser
Simple API with minimal configuration required
Wide adoption and community support

Cons of marked

Limited extensibility compared to unified's plugin system
Focuses primarily on Markdown, while unified supports multiple formats
Less granular control over parsing and transformation process

Code comparison

marked:

import marked from 'marked';

const html = marked('# Hello, world!');
console.log(html);

unified:

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkHtml from 'remark-html';

const html = await unified()
  .use(remarkParse)
  .use(remarkHtml)
  .process('# Hello, world!');
console.log(String(html));

Summary

marked is a lightweight and fast Markdown parser with a simple API, making it ideal for straightforward Markdown-to-HTML conversion. unified, on the other hand, offers a more flexible and extensible ecosystem for working with various content formats, including Markdown. While marked excels in simplicity and speed, unified provides greater control and customization options through its plugin system and support for multiple formats.

markdown-it

18,123

Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed

Pros of markdown-it

Lightweight and fast performance
Extensive plugin ecosystem for customization
Easy to use with a simple API

Cons of markdown-it

Limited to Markdown processing only
Less flexibility for handling other markup languages
Smaller community compared to unified

Code Comparison

markdown-it:

const md = require('markdown-it')();
const result = md.render('# Hello, world!');

unified:

const unified = require('unified');
const markdown = require('remark-parse');
const html = require('remark-html');

unified()
  .use(markdown)
  .use(html)
  .process('# Hello, world!', (err, file) => {
    console.log(String(file));
  });

Summary

markdown-it is a lightweight and fast Markdown parser with a focus on extensibility through plugins. It's easy to use and performs well for Markdown-specific tasks. However, it's limited to Markdown processing and has a smaller community compared to unified.

unified, on the other hand, is a more comprehensive ecosystem for processing various markup languages, including Markdown. It offers greater flexibility and a larger community but may have a steeper learning curve and slightly more complex setup for simple Markdown tasks.

Choose markdown-it for straightforward Markdown processing with good performance, or unified for a more versatile solution that can handle multiple markup languages and complex transformations.

remarkable

5,743

Pros of Remarkable

Lightweight and fast Markdown parser
Simple API with minimal configuration required
Supports CommonMark specification out of the box

Cons of Remarkable

Limited extensibility compared to Unified's plugin ecosystem
Less active development and community support
Focused solely on Markdown, while Unified supports multiple formats

Code Comparison

Remarkable:

var md = new Remarkable();
var result = md.render('# Hello, world!');

Unified:

unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('# Hello, world!')
  .then((file) => console.log(String(file)));

Key Differences

Unified provides a more modular and extensible architecture
Remarkable is more straightforward for simple Markdown parsing tasks
Unified supports a wider range of document formats and transformations
Remarkable has a smaller learning curve for basic usage
Unified offers greater flexibility for complex document processing pipelines

Use Cases

Choose Remarkable for quick and simple Markdown parsing
Opt for Unified when working with multiple formats or requiring extensive customization
Unified is better suited for large-scale projects with complex document processing needs
Remarkable is ideal for lightweight applications with basic Markdown requirements

showdown

14,258

A bidirectional Markdown to HTML to Markdown converter written in Javascript

Pros of Showdown

Simpler and more lightweight, focusing specifically on Markdown to HTML conversion
Easier to set up and use for basic Markdown processing tasks
Supports GitHub Flavored Markdown (GFM) out of the box

Cons of Showdown

Less extensible and customizable compared to Unified's plugin ecosystem
Limited to Markdown-to-HTML conversion, while Unified supports multiple formats and transformations
Lacks advanced features like AST manipulation and syntax tree traversal

Code Comparison

Showdown:

const converter = new showdown.Converter();
const html = converter.makeHtml('# Hello, Markdown!');

Unified:

const unified = require('unified');
const markdown = require('remark-parse');
const html = require('remark-html');

unified()
  .use(markdown)
  .use(html)
  .process('# Hello, Markdown!', (err, file) => console.log(String(file)));

Summary

Showdown is a simpler, more focused library for Markdown-to-HTML conversion, making it easier to use for basic tasks. Unified, on the other hand, offers a more powerful and extensible ecosystem for processing various formats, including Markdown, with advanced features like AST manipulation. Choose Showdown for quick and straightforward Markdown conversion, or opt for Unified when you need more flexibility and advanced processing capabilities.

commonmark.js

1,436

CommonMark parser and renderer in JavaScript

Pros of commonmark.js

Focused specifically on CommonMark parsing and rendering
Lightweight and fast implementation
Strict adherence to the CommonMark specification

Cons of commonmark.js

Limited to CommonMark syntax only
Less extensible for custom syntax or processing

Code Comparison

commonmark.js:

var reader = new commonmark.Parser();
var writer = new commonmark.HtmlRenderer();
var parsed = reader.parse("Hello *world*");
var result = writer.render(parsed);

unified:

unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process("Hello *world*")
  .then((file) => console.log(String(file)));

Key Differences

unified is a more comprehensive ecosystem for parsing, transforming, and generating content
unified supports various syntax types beyond Markdown (e.g., HTML, XML)
unified offers a plugin system for extending functionality
commonmark.js is more suitable for projects strictly adhering to CommonMark
unified provides a unified interface for working with different content types

Use Cases

Choose commonmark.js for lightweight CommonMark parsing and rendering
Opt for unified when working with multiple content types or requiring extensive customization

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

unified lets you inspect and transform content with plugins.

What is this?
When should I use this?
Install
Use
Overview
API
Types
Compatibility
Contribute
Sponsor
Acknowledgments
License

What is this?

unified is two things:

unified is a collective of 500+ free and open source packages that work with content as structured data (ASTs)
unified (this project) is the core package, used in 1.3m+ projects on GH, to process content with plugins

Several ecosystems are built on unified around different kinds of content. Notably, remark (markdown), rehype (HTML), and retext (natural language). These ecosystems can be connected together.

for more about us, see unifiedjs.com
for updates, see @unifiedjs on Twitter
for questions, see support
to help, see contribute and sponsor below

When should I use this?

In some cases, you are already using unified. For example, itâs used in MDX, Gatsby, Docusaurus, etc. In those cases, you donât need to add unified yourself but you can include plugins into those projects.

But the real fun (for some) is to get your hands dirty and work with syntax trees and build with it yourself. You can create those projects, or things like Prettier, or your own site generator. You can connect utilities together and make your own plugins that check for problems and transform from one thing to another.

When you are dealing with one type of content (such as markdown), you can use the main package of that ecosystem instead (so remark). When you are dealing with different kinds of content (such as markdown and HTML), itâs recommended to use unified itself, and pick and choose the plugins you need.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install unified

In Deno with esm.sh:

import {unified} from 'https://esm.sh/unified@11'

In browsers with esm.sh:

<script type="module">
  import {unified} from 'https://esm.sh/unified@11?bundle'
</script>

Use

import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'
import {reporter} from 'vfile-reporter'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeDocument, {title: 'ðð'})
  .use(rehypeFormat)
  .use(rehypeStringify)
  .process('# Hello world!')

console.error(reporter(file))
console.log(String(file))

Yields:

no issues found

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>ðð</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>

Overview

unified is an interface for processing content with syntax trees. Syntax trees are a representation of content understandable to programs. Those programs, called plugins, take these trees and inspect and modify them. To get to the syntax tree from text, there is a parser. To get from that back to text, there is a compiler. This is the process of a processor.

| ........................ process ........................... |
| .......... parse ... | ... run ... | ... stringify ..........|

          +--------+                     +----------+
Input ->- | Parser | ->- Syntax Tree ->- | Compiler | ->- Output
          +--------+          |          +----------+
                              X
                              |
                       +--------------+
                       | Transformers |
                       +--------------+

Processors

Processors process content. On its own, unified (the root processor) doesnât work. It needs to be configured with plugins to work. For example:

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

That processor can do different things. It can:

â¦parse markdown (parse)
â¦turn parsed markdown into HTML and format the HTML (run)
â¦compile HTML (stringify)
â¦do all of the above (process)

Every processor implements another processor. To create a processor, call another processor. The new processor is configured to work the same as its ancestor. But when the descendant processor is configured in the future it does not affect the ancestral processor.

When processors are exposed from a module (for example, unified itself) they should not be configured directly, as that would change their behavior for all module users. Those processors are frozen and they should be called to create a new processor before they are used.

File

When processing a document, metadata is gathered about that document. vfile is the file format that stores data, metadata, and messages about files for unified and plugins.

There are several utilities for working with these files.

Syntax tree

The syntax trees used in unified are unist nodes. A tree represents a whole document and each node is a plain JavaScript object with a type field. The semantics of nodes and the format of syntax trees is defined by other projects:

esast â JavaScript
hast â HTML
mdast â markdown
nlcst â natural language
xast â XML

There are many utilities for working with trees listed in each aforementioned project and maintained in the syntax-tree organization. These utilities are a level lower than unified itself and are building blocks that can be used to make plugins.

Ecosystems

Around each syntax tree is an ecosystem that focusses on that particular kind of content. At their core, they parse text to a tree and compile that tree back to text. They also provide plugins that work with the syntax tree, without requiring that the end user has knowledge about that tree.

rehype (hast) â HTML
remark (mdast) â markdown
retext (nlcst) â natural language

Plugins

Each aforementioned ecosystem comes with a large set of plugins that you can pick and choose from to do all kinds of things.

List of remark plugins Â· remarkjs/awesome-remark Â· remark-plugin topic
List of rehype plugins Â· rehypejs/awesome-rehype Â· rehype-plugin topic
List of retext plugins Â· retextjs/awesome-retext Â· retext-plugin topic

There are also a few plugins that work in any ecosystem:

unified-diff â ignore unrelated messages in GitHub Actions and Travis
unified-infer-git-meta â infer metadata of a document from Git
unified-message-control â enable, disable, and ignore messages from content

Configuration

Processors are configured with plugins or with the data method. Most plugins also accept configuration through options. See each pluginâs readme for more info.

Integrations

unified can integrate with the file system through unified-engine. CLI apps can be created with unified-args, Gulp plugins with unified-engine-gulp, and language servers with unified-language-server. A streaming interface can be created with unified-stream.

Programming interface

The API provided by unified allows multiple files to be processed and gives access to metadata (such as lint messages):

import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-style-guide'
import remarkRehype from 'remark-rehype'
import remarkRetext from 'remark-retext'
import retextEnglish from 'retext-english'
import retextEquality from 'retext-equality'
import {unified} from 'unified'
import {reporter} from 'vfile-reporter'

const file = await unified()
  .use(remarkParse)
  .use(remarkPresetLintMarkdownStyleGuide)
  .use(remarkRetext, unified().use(retextEnglish).use(retextEquality))
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('*Emphasis* and _stress_, you guys!')

console.error(reporter(file))
console.log(String(file))

Yields:

1:16-1:24 warning Emphasis should use `*` as a marker                                 emphasis-marker remark-lint
1:30-1:34 warning `guys` may be insensitive, use `people`, `persons`, `folks` instead gals-man        retext-equality

â  2 warnings

<p><em>Emphasis</em> and <em>stress</em>, you guys!</p>

Transforming between ecosystems

Ecosystems can be combined in two modes.

Bridge mode transforms the tree from one format (origin) to another (destination). A different processor runs on the destination tree. Afterwards, the original processor continues with the origin tree.

Mutate mode also transforms the syntax tree from one format to another. But the original processor continues transforming the destination tree.

In the previous example (âProgramming interfaceâ), remark-retext is used in bridge mode: the origin syntax tree is kept after retext is done; whereas remark-rehype is used in mutate mode: it sets a new syntax tree and discards the origin tree.

The following plugins lets you combine ecosystems:

remark-retext â turn markdown into natural language
remark-rehype â turn markdown into HTML
rehype-retext â turn HTML into natural language
rehype-remark â turn HTML into markdown

API

This package exports the identifier unified (the root processor). There is no default export.

`processor()`

Create a new processor.

Returns

New unfrozen processor (processor).

This processor is configured to work the same as its ancestor. When the descendant processor is configured in the future it does not affect the ancestral processor.

Example

This example shows how a new processor can be created (from remark) and linked to stdin(4) and stdout(4).

import process from 'node:process'
import concatStream from 'concat-stream'
import {remark} from 'remark'

process.stdin.pipe(
  concatStream(function (buf) {
    process.stdout.write(String(remark().processSync(buf)))
  })
)

`processor.compiler`

Compiler to use (Compiler, optional).

`processor.data([key[, value]])`

Configure the processor with info available to all plugins. Information is stored in an object.

Typically, options can be given to a specific plugin, but sometimes it makes sense to have information shared with several plugins. For example, a list of HTML elements that are self-closing, which is needed during all phases.

ð Note: setting information cannot occur on frozen processors. Call the processor first to create a new unfrozen processor.

ð Note: to register custom data in TypeScript, augment the Data interface.

Signatures

processor = processor.data(key, value)
processor = processor.data(dataset)
value = processor.data(key)
dataset = processor.data()

Parameters

key (keyof Data, optional) â field to get
value (Data[key]) â value to set
values (Data) â values to set

Returns

The current processor when setting (processor), the value at key when getting (Data[key]), or the entire dataset when getting without key (Data).

Example

This example show how to get and set info:

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'}

`processor.freeze()`

Freeze a processor.

Frozen processors are meant to be extended and not to be configured directly.

When a processor is frozen it cannot be unfrozen. New processors working the same way can be created by calling the processor.

Itâs possible to freeze processors explicitly by calling .freeze(). Processors freeze automatically when .parse(), .run(), .runSync(), .stringify(), .process(), or .processSync() are called.

Returns

The current processor (processor).

Example

This example, index.js, shows how rehype prevents extensions to itself:

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

export const rehype = unified().use(rehypeParse).use(rehypeStringify).freeze()

That processor can be used and configured like so:

import {rehype} from 'rehype'
import rehypeFormat from 'rehype-format'
// â¦

rehype()
  .use(rehypeFormat)
  // â¦

A similar looking example is broken as operates on the frozen interface. If this behavior was allowed it would result in unexpected behavior so an error is thrown. This is not valid:

import {rehype} from 'rehype'
import rehypeFormat from 'rehype-format'
// â¦

rehype
  .use(rehypeFormat)
  // â¦

Yields:

~/node_modules/unified/index.js:426
    throw new Error(
    ^

Error: Cannot call `use` on a frozen processor.
Create a new processor first, by calling it: use `processor()` instead of `processor`.
    at assertUnfrozen (~/node_modules/unified/index.js:426:11)
    at Function.use (~/node_modules/unified/index.js:165:5)
    â¦

`processor.parse(file)`

Parse text to a syntax tree.

ð Note: parse freezes the processor if not already frozen.

ð Note: parse performs the parse phase, not the run phase or other phases.

Parameters

file (Compatible) â file to parse; typically string or VFile; any value accepted as x in new VFile(x)

Returns

Syntax tree representing file (Node).

Example

This example shows how parse can be used to create a tree from a file.

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

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

console.log(tree)

Yields:

{
  type: 'root',
  children: [
    {type: 'heading', depth: 1, children: [Array], position: [Object]}
  ],
  position: {
    start: {line: 1, column: 1, offset: 0},
    end: {line: 1, column: 15, offset: 14}
  }
}

`processor.parser`

Parser to use (Parser, optional).

`processor.process(file[, done])`

Process the given file as configured on the processor.

ð Note: process freezes the processor if not already frozen.

ð Note: process performs the parse, run, and stringify phases.

Signatures

processor.process(file, done)
Promise<VFile> = processor.process(file?)

Parameters

file (Compatible, optional) â file; typically string or VFile; any value accepted as x in new VFile(x)
done (ProcessCallback, optional) â callback

Returns

Nothing if done is given (undefined). Otherwise a promise, rejected with a fatal error or resolved with the processed file (Promise<VFile>).

The parsed, transformed, and compiled value is available at file.value (see note).

ð Note: unified typically compiles by serializing: most compilers return string (or Uint8Array). Some compilers, such as the one configured with rehype-react, return other values (in this case, a React tree). If youâre using a compiler that doesnât serialize, expect different result values.

To register custom results in TypeScript, add them to CompileResultMap.

Example

This example shows how process can be used to process a file:

import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeDocument, {title: 'ðð'})
  .use(rehypeFormat)
  .use(rehypeStringify)
  .process('# Hello world!')

console.log(String(file))

Yields:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>ðð</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>

`processor.processSync(file)`

Process the given file as configured on the processor.

An error is thrown if asynchronous transforms are configured.

ð Note: processSync freezes the processor if not already frozen.

ð Note: processSync performs the parse, run, and stringify phases.

Parameters

file (Compatible, optional) â file; typically string or VFile; any value accepted as x in new VFile(x)

Returns

The processed file (VFile).

The parsed, transformed, and compiled value is available at file.value (see note).

ð Note: unified typically compiles by serializing: most compilers return string (or Uint8Array). Some compilers, such as the one configured with rehype-react, return other values (in this case, a React tree). If youâre using a compiler that doesnât serialize, expect different result values.

To register custom results in TypeScript, add them to CompileResultMap.

Example

This example shows how processSync can be used to process a file, if all transformers are synchronous.

import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

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

console.log(String(processor.processSync('# Hello world!')))

Yields:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>ðð</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>

`processor.run(tree[, file][, done])`

Run transformers on a syntax tree.

ð Note: run freezes the processor if not already frozen.

ð Note: run performs the run phase, not other phases.

Signatures

processor.run(tree, done)
processor.run(tree, file, done)
Promise<Node> = processor.run(tree, file?)

Parameters

tree (Node) â tree to transform and inspect
file (Compatible, optional) â file associated with node; any value accepted as x in new VFile(x)
done (RunCallback, optional) â callback

Returns

Nothing if done is given (undefined). Otherwise, a promise rejected with a fatal error or resolved with the transformed tree (Promise<Node>).

Example

This example shows how run can be used to transform a tree:

import remarkReferenceLinks from 'remark-reference-links'
import {unified} from 'unified'
import {u} from 'unist-builder'

const tree = u('root', [
  u('paragraph', [
    u('link', {href: 'https://example.com'}, [u('text', 'Example Domain')])
  ])
])

const changedTree = await unified().use(remarkReferenceLinks).run(tree)

console.log(changedTree)

Yields:

{
  type: 'root',
  children: [
    {type: 'paragraph', children: [Array]},
    {type: 'definition', identifier: '1', title: '', url: undefined}
  ]
}

`processor.runSync(tree[, file])`

Run transformers on a syntax tree.

An error is thrown if asynchronous transforms are configured.

ð Note: runSync freezes the processor if not already frozen.

ð Note: runSync performs the run phase, not other phases.

Parameters

tree (Node) â tree to transform and inspect
file (Compatible, optional) â file associated with node; any value accepted as x in new VFile(x)

Returns

Transformed tree (Node).

`processor.stringify(tree[, file])`

Compile a syntax tree.

ð Note: stringify freezes the processor if not already frozen.

ð Note: stringify performs the stringify phase, not the run phase or other phases.

Parameters

tree (Node) â tree to compile
file (Compatible, optional) â file associated with node; any value accepted as x in new VFile(x)

Returns

Textual representation of the tree (Uint8Array or string, see note).

ð Note: unified typically compiles by serializing: most compilers return string (or Uint8Array). Some compilers, such as the one configured with rehype-react, return other values (in this case, a React tree). If youâre using a compiler that doesnât serialize, expect different result values.

To register custom results in TypeScript, add them to CompileResultMap.

Example

This example shows how stringify can be used to serialize a syntax tree:

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)

Yields:

<h1>Hello world!</h1>

`processor.use(plugin[, options])`

Configure the processor to use a plugin, a list of usable values, or a preset.

If the processor is already using a plugin, the previous plugin configuration is changed based on the options that are passed in. In other words, the plugin is not added a second time.

ð Note: use cannot be called on frozen processors. Call the processor first to create a new unfrozen processor.

Signatures

processor.use(preset?)
processor.use(list)
processor.use(plugin[, ...parameters])

Parameters

preset (Preset) â plugins and settings
list (PluggableList) â list of usable things
plugin (Plugin) â plugin
parameters (Array<unknown>) â configuration for plugin, typically a single options object

Returns

Current processor (processor).

Example

There are many ways to pass plugins to .use(). This example gives an overview:

import {unified} from 'unified'

unified()
  // Plugin with options:
  .use(pluginA, {x: true, y: true})
  // Passing the same plugin again merges configuration (to `{x: true, y: false, z: true}`):
  .use(pluginA, {y: false, z: true})
  // Plugins:
  .use([pluginB, pluginC])
  // Two plugins, the second with options:
  .use([pluginD, [pluginE, {}]])
  // Preset with plugins and settings:
  .use({plugins: [pluginF, [pluginG, {}]], settings: {position: false}})
  // Settings only:
  .use({settings: {position: false}})

`CompileResultMap`

Interface of known results from compilers (TypeScript type).

Normally, compilers result in text (Value of vfile). When you compile to something else, such as a React node (as in, rehype-react), you can augment this interface to include that type.

import type {ReactNode} from 'somewhere'

declare module 'unified' {
  interface CompileResultMap {
    // Register a new result (value is used, key should match it).
    ReactNode: ReactNode
  }
}

export {} // You may not need this, but it makes sure the file is a module.

Use CompileResults to access the values.

Type

interface CompileResultMap {
  // Note: if `Value` from `VFile` is changed, this should too.
  Uint8Array: Uint8Array
  string: string
}

`CompileResults`

Acceptable results from compilers (TypeScript type).

To register custom results, add them to CompileResultMap.

Type

type CompileResults = CompileResultMap[keyof CompileResultMap]

`Compiler`

A compiler handles the compiling of a syntax tree to something else (in most cases, text) (TypeScript type).

It is used in the stringify phase and called with a Node and VFile representation of the document to compile. It should return the textual representation of the given tree (typically string).

ð Note: unified typically compiles by serializing: most compilers return string (or Uint8Array). Some compilers, such as the one configured with rehype-react, return other values (in this case, a React tree). If youâre using a compiler that doesnât serialize, expect different result values.

To register custom results in TypeScript, add them to CompileResultMap.

Type

type Compiler<
  Tree extends Node = Node,
  Result extends CompileResults = CompileResults
> = (tree: Tree, file: VFile) => Result

`Data`

Interface of known data that can be supported by all plugins (TypeScript type).

To type this, do something like:

declare module 'unified' {
  interface Data {
    htmlVoidElements?: Array<string> | undefined
  }
}

export {} // You may not need this, but it makes sure the file is a module.

Type

interface Data {
  settings?: Settings | undefined
}

See Settings for more info.

`Parser`

A parser handles the parsing of text to a syntax tree (TypeScript type).

It is used in the parse phase and is called with a string and VFile of the document to parse. It must return the syntax tree representation of the given file (Node).

Type

type Parser<Tree extends Node = Node> = (document: string, file: VFile) => Tree

`Pluggable`

Union of the different ways to add plugins and settings (TypeScript type).

Type

type Pluggable =
  | Plugin<Array<any>, any, any>
  | PluginTuple<Array<any>, any, any>
  | Preset

See Plugin, PluginTuple, and Preset for more info.

`PluggableList`

List of plugins and presets (TypeScript type).

Type

type PluggableList = Array<Pluggable>

See Pluggable for more info.

`Plugin`

Single plugin (TypeScript type).

Plugins configure the processors they are applied on in the following ways:

they change the processor, such as the parser, the compiler, or by configuring data
they specify how to handle trees and files

In practice, they are functions that can receive options and configure the processor (this).

ð Note: plugins are called when the processor is frozen, not when they are applied.

Type

type Plugin<
  PluginParameters extends unknown[] = [],
  Input extends Node | string | undefined = Node,
  Output = Input
> = (
  this: Processor,
  ...parameters: PluginParameters
) => Input extends string // Parser.
  ? Output extends Node | undefined
    ? undefined | void
    : never
  : Output extends CompileResults // Compiler.
  ? Input extends Node | undefined
    ? undefined | void
    : never
  : // Inspect/transform.
      | Transformer<
          Input extends Node ? Input : Node,
          Output extends Node ? Output : Node
        >
      | undefined
      | void

See Transformer for more info.

Example

move.js:

/**
 * @import {Plugin} from 'unified'
 */

/**
 * @typedef Options
 *   Configuration (required).
 * @property {string} extname
 *   File extension to use (must start with `.`).
 */

/** @type {Plugin<[Options]>} */
export function move(options) {
  if (!options || !options.extname) {
    throw new Error('Missing `options.extname`')
  }

  return function (_, file) {
    if (file.extname && file.extname !== options.extname) {
      file.extname = options.extname
    }
  }
}

example.md:

# Hello, world!

example.js:

import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read, write} from 'to-vfile'
import {unified} from 'unified'
import {reporter} from 'vfile-reporter'
import {move} from './move.js'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(move, {extname: '.html'})
  .use(rehypeStringify)
  .process(await read('example.md'))

console.error(reporter(file))
await write(file) // Written to `example.html`.

Yields:

example.md: no issues found

â¦and in example.html:

<h1>Hello, world!</h1>

`PluginTuple`

Tuple of a plugin and its configuration (TypeScript type).

The first item is a plugin, the rest are its parameters.

Type

type PluginTuple<
  TupleParameters extends unknown[] = [],
  Input extends Node | string | undefined = undefined,
  Output = undefined
> = [
  plugin: Plugin<TupleParameters, Input, Output>,
  ...parameters: TupleParameters
]

See Plugin for more info.

`Preset`

Sharable configuration (TypeScript type).

They can contain plugins and settings.

Fields

plugins (PluggableList, optional) â list of plugins and presets
settings (Data, optional) â shared settings for parsers and compilers

Example

preset.js:

/**
 * @import {Preset} from 'unified'
 */

import remarkCommentConfig from 'remark-comment-config'
import remarkLicense from 'remark-license'
import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
import remarkToc from 'remark-toc'

/** @type {Preset} */
const preset = {
  plugins: [
    remarkPresetLintRecommended,
    remarkPresetLintConsistent,
    remarkCommentConfig,
    [remarkToc, {maxDepth: 3, tight: true}],
    remarkLicense
  ],
  settings: {bullet: '*', emphasis: '*', fences: true},
}

export default preset

example.md:

# Hello, world!

_Emphasis_ and **importance**.

## Table of contents

## API

## License

example.js:

import {remark} from 'remark'
import {read, write} from 'to-vfile'
import {reporter} from 'vfile-reporter'
import preset from './preset.js'

const file = await remark()
  .use(preset)
  .process(await read('example.md'))

console.error(reporter(file))
await write(file)

Yields:

example.md: no issues found

example.md now contains:

# Hello, world!

*Emphasis* and **importance**.

## Table of contents

*   [API](#api)
*   [License](#license)

## API

## License

[MIT](license) Â© [Titus Wormer](https://wooorm.com)

`ProcessCallback`

Callback called when the process is done (TypeScript type).

Called with either an error or a result.

Parameters

error (Error, optional) â fatal error
file (VFile, optional) â processed file

Returns

Nothing (undefined).

Example

This example shows how process can be used to process a file with a callback.

import remarkGithub from 'remark-github'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'
import {reporter} from 'vfile-reporter'

unified()
  .use(remarkParse)
  .use(remarkGithub)
  .use(remarkStringify)
  .process('@unifiedjs', function (error, file) {
    if (error) throw error
    if (file) {
      console.error(reporter(file))
      console.log(String(file))
    }
  })

Yields:

no issues found

[**@unifiedjs**](https://github.com/unifiedjs)

`Processor`

Type of a processor (TypeScript type).

`RunCallback`

Callback called when transformers are done (TypeScript type).

Called with either an error or results.

Parameters

error (Error, optional) â fatal error
tree (Node, optional) â transformed tree
file (VFile, optional) â file

Returns

Nothing (undefined).

`Settings`

Interface of known extra options, that can be supported by parser and compilers.

This exists so that users can use packages such as remark, which configure both parsers and compilers (in this case remark-parse and remark-stringify), and still provide options for them.

When you make parsers or compilers, that could be packaged up together, you should support this.data('settings') as input and merge it with explicitly passed options. Then, to type it, using remark-stringify as an example, do something like:

declare module 'unified' {
  interface Settings {
    bullet: '*' | '+' | '-'
    // â¦
  }
}

export {} // You may not need this, but it makes sure the file is a module.

Type

interface Settings {}

`TransformCallback`

Callback passed to transforms (TypeScript type).

If the signature of a transformer accepts a third argument, the transformer may perform asynchronous operations, and must call it.

Parameters

error (Error, optional) â fatal error to stop the process
tree (Node, optional) â new, changed, tree
file (VFile, optional) â new, changed, file

Returns

Nothing (undefined).

`Transformer`

Transformers handle syntax trees and files (TypeScript type).

They are functions that are called each time a syntax tree and file are passed through the run phase. When an error occurs in them (either because itâs thrown, returned, rejected, or passed to next), the process stops.

The run phase is handled by trough, see its documentation for the exact semantics of these functions.

ð Note: you should likely ignore next: donât accept it. it supports callback-style async work. But promises are likely easier to reason about.

Type

type Transformer<
  Input extends Node = Node,
  Output extends Node = Input
> = (
  tree: Input,
  file: VFile,
  next: TransformCallback<Output>
) =>
  | Promise<Output | undefined>
  | Output
  | Error
  | undefined

Types

This package is fully typed with TypeScript. It exports the additional types CompileResultMap, CompileResults, Compiler, Data, Parser, Pluggable, PluggableList, Plugin, PluginTuple, Preset, ProcessCallback, Processor, RunCallback, Settings, TransformCallback, and Transformer

For TypeScript to work, it is particularly important to type your plugins correctly. We strongly recommend using the Plugin type with its generics and to use the node types for the syntax trees provided by our packages (as in, @types/hast, @types/mdast, @types/nlcst).

/**
 * @import {Root as HastRoot} from 'hast'
 * @import {Root as MdastRoot} from 'mdast'
 * @import {Plugin} from 'unified'
 */

/**
 * @typedef Options
 *   Configuration (optional).
 * @property {boolean | null | undefined} [someField]
 *   Some option (optional).
 */

// To type options:
/** @type {Plugin<[(Options | null | undefined)?]>} */
export function myPluginAcceptingOptions(options) {
  const settings = options || {}
  // `settings` is now `Options`.
}

// To type a plugin that works on a certain tree, without options:
/** @type {Plugin<[], MdastRoot>} */
export function myRemarkPlugin() {
  return function (tree, file) {
    // `tree` is `MdastRoot`.
  }
}

// To type a plugin that transforms one tree into another:
/** @type {Plugin<[], MdastRoot, HastRoot>} */
export function remarkRehype() {
  return function (tree) {
    // `tree` is `MdastRoot`.
    // Result must be `HastRoot`.
  }
}

// To type a plugin that defines a parser:
/** @type {Plugin<[], string, MdastRoot>} */
export function remarkParse(options) {}

// To type a plugin that defines a compiler:
/** @type {Plugin<[], HastRoot, string>} */
export function rehypeStringify(options) {}

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, unified@^11, compatible with Node.js 16.

Contribute

See contributing.md in unifiedjs/.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.

For info on how to submit a security report, see our security policy.

Sponsor

Support this effort and give back by sponsoring on OpenCollective!

Vercel	Motif	HashiCorp		American Express		GitBook

Gatsby	Netlify	Coinbase	ThemeIsle	Expo	Boost Note	Markdown Space	Holloway
		You?

Acknowledgments

Preliminary work for unified was done in 2014 for retext and inspired by ware. Further incubation happened in remark. The project was finally externalised in 2015 and published as unified. The project was authored by @wooorm.

Although unified since moved its plugin architecture to trough, thanks to @calvinfo, @ianstormtaylor, and others for their work on ware, as it was a huge initial inspiration.

License

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of remark

Cons of remark

Code Comparison

Summary

Pros of marked

Cons of marked

Code comparison

Summary

Pros of markdown-it

Cons of markdown-it

Code Comparison

Summary

Pros of Remarkable

Cons of Remarkable

Code Comparison

Key Differences

Use Cases

Pros of Showdown

Cons of Showdown

Code Comparison

Summary

Pros of commonmark.js

Cons of commonmark.js

Code Comparison

Key Differences

Use Cases

Convert designs to code with AI

README

Contents

What is this?

When should I use this?

Install

Use

Overview

Processors

File

Syntax tree

Ecosystems

Plugins

Configuration

Integrations

Programming interface

Transforming between ecosystems

API

processor()

Returns

Example

processor.compiler

processor.data([key[, value]])

Signatures

Parameters

Returns

Example

processor.freeze()

Returns

Example

processor.parse(file)

Parameters

Returns

Example

processor.parser

processor.process(file[, done])

Signatures

Parameters

Returns

Example

processor.processSync(file)

Parameters

Returns

Example

processor.run(tree[, file][, done])

Signatures

Parameters

`processor()`

`processor.compiler`

`processor.data([key[, value]])`

`processor.freeze()`

`processor.parse(file)`

`processor.parser`

`processor.process(file[, done])`

`processor.processSync(file)`

`processor.run(tree[, file][, done])`

`processor.runSync(tree[, file])`

`processor.stringify(tree[, file])`

`processor.use(plugin[, options])`

`CompileResultMap`

`CompileResults`

`Compiler`

`Data`

`Parser`

`Pluggable`

`PluggableList`

`Plugin`

`PluginTuple`

`Preset`

`ProcessCallback`

`Processor`

`RunCallback`

`Settings`

`TransformCallback`

`Transformer`