The unified npm package is an interface for parsing, inspecting, transforming, and serializing content through syntax trees. It is built on the concept of syntax trees and is often used to work with content in markdown, HTML, and plain text formats. Unified is part of the unified collective which provides a range of plugins and utilities for content processing.
Parsing Markdown to Syntax Trees
This feature allows you to parse Markdown content into an abstract syntax tree (AST) using the remark-parse plugin.
const unified = require('unified');
const markdown = require('remark-parse');
const processor = unified().use(markdown);
const tree = processor.parse('# Hello world');
console.log(tree);Transforming Syntax Trees
This feature demonstrates transforming a Markdown AST to an HTML AST and then serializing it to an HTML string.
const unified = require('unified');
const markdown = require('remark-parse');
const remark2rehype = require('remark-rehype');
const html = require('rehype-stringify');
const processor = unified()
.use(markdown)
.use(remark2rehype)
.use(html);
const file = processor.processSync('# Hello world');
console.log(String(file));Linting and Validating Markdown
This feature shows how to use unified with remark-lint to lint and validate Markdown content.
const unified = require('unified');
const markdown = require('remark-parse');
const remarkLint = require('remark-lint');
const processor = unified()
.use(markdown)
.use(remarkLint);
processor.process('# Hello world', function (err, file) {
console.error(report(err || file));
});Compiling Markdown to HTML
This feature illustrates compiling Markdown to a fully formatted HTML document.
const unified = require('unified');
const markdown = require('remark-parse');
const remark2rehype = require('remark-rehype');
const doc = require('rehype-document');
const format = require('rehype-format');
const html = require('rehype-stringify');
const processor = unified()
.use(markdown)
.use(remark2rehype)
.use(doc)
.use(format)
.use(html);
const file = processor.processSync('# Hello world');
console.log(String(file));markdown-it is a Markdown parser with a focus on speed and extensibility. It is similar to unified in that it can parse and render Markdown, but it does not use an AST or provide the same plugin ecosystem.
remarkable is another Markdown parser and renderer. It offers a similar feature set to markdown-it but also does not use an AST or have the extensive plugin system that unified offers.
showdown is a JavaScript Markdown to HTML converter. It is similar to unified in that it converts Markdown to HTML, but it does not provide a unified interface for parsing, transforming, and serializing content.
Text processing framework: Parse / Transform / Compile.
This library provides the boilerplate to make parsing and compiling pluggable. It’s in use by mdast and retext.
npm:
npm install unified
unified is also available for bower, component, and duo, and as an AMD, CommonJS, and globals module, uncompressed and compressed.
From mdast:
var unified = require('unified');
var Parser = require('./lib/parse.js');
var Compiler = require('./lib/stringify.js');
module.exports = unified({
'name': 'mdast',
'type': 'ast',
'Parser': Parser,
'Compiler': Compiler
});
Create a new Processor constructor.
Parameters — options (Object):
name (string) — Unique namespace, e.g. 'mdast' or 'retext'.
type (string) — Type of the produced syntax tree. For example,
mdast uses an 'ast' (Abstract Syntax Tree), whereas retext
uses a 'cst' (Concrete Syntax Tree).
Used to store the syntax tree after parsing on the file (at
file.namespace(name)[type]).
Parser (Function) — Constructor which transforms a virtual file
into a syntax tree. When input is parsed, this function will be
constructed with a file and settings. Parser instances should
have a parse method which returns a node (an object with a type
property).
The string representation of a file can be accessed by executing
file.toString();.
Compiler (Function) — Constructor which transforms a node
into a string. When input is compiled, this function will be
constructed with a file and settings. Compiler instances should
have a compile method which returns a string.
The syntax tree representation of a file can be accessed by executing
file.namespace(name)[type].
Returns — Function (Processor constructor).
Note that all methods on the instance are also available as functions on the constructor, which, when invoked, create a new instance.
Thus, invoking
new Processor().process()is the same asProcessor.process().
Create a new Processor instance.
Parameters
processor (Processor, optional) — Uses all plug-ins available on the
reference processor instance, on the newly constructed processor instance.Returns
Processor.
The constructors passed to unified at 'Parser'
and 'Compiler' are stored on Processor instances. The Parser
is responsible for parsing a virtual file into a syntax tree, and the
Compiler for compiling a syntax tree into something else.
When a processor is constructed, both are passed to unherit, which ensures that plug-ins can change how the processor instance parses and compiles without affecting other processors.
Parsers must have a parse method, Compilers a compile method.
Change the way the processor works by using a plugin.
Signatures
unified = unified.use(plugin[, input...]);unified = unified.use(plugins).Parameters
plugin (Function) — Plugin.plugins (Array.<Function>) — List of plugins.input (*) — Passed to plugin. Specified by its documentation.Returns
Processor — this (the context object).
A uniware plugin changes the way the applied-on processor works. It does two things:
Both have their own function. The first is called an “attacher”. The second is named a “transformer”. An “attacher” may return a “transformer”.
To modify the processor, create an attacher. An attacher is the thing passed to
use. It can
receive plugin specific options, but that’s entirely up to the third-party
developer.
An attacher is invoked when the plugin is
used, and can
return a transformer which will be called on subsequent
process()s and
run()s.
Signatures
transformer? = attacher(processor[, input...]).Parameters
processor (Processor) — Context on which the plugin was
used;
input (*) — Passed by the user of a plug-in.
Returns
transformer (optional).
To transform a syntax tree, create a transformer. A transformer is a simple
(generator) function which is invoked each time a file is
process()s and
run()s. A transformer should
change the syntax tree representation of a file.
Signatures
err? = transformer(node, file);transformer(node, file, next);Promise.<null, Error> = transformer(node, file);transformer*(node, file).Parameters
node (Node) — Syntax tree representation of a file;
file (VFile) — Virtual file;
next (function([err]), optional) — If the signature includes both
next, transformer may finish asynchronous, and must
invoke next() on completion with an optional error.
Returns — Optionally:
Error — Exception which will be thrown;
Promise.<null, Error> — Promise which must be resolved or rejected
on completion.
Parse a document into a syntax tree.
When given a file, stores the returned node on that file.
Signatures
node = processor.parse(file|value[, options]).Parameters
file (VFile) — Virtual file.value (string) — String representation of a file.options (Object) — Configuration given to the parser.Returns
Node — (Object).
Transform a syntax tree by applying plug-ins to it.
Either a node or a file which was previously passed to processor.parse(),
must be given.
Signatures
node = processor.run(node[, file|value][, done]);node = processor.run(file[, done]).Parameters
node (Object) — Syntax tree as returned by parse();file (VFile) — Virtual file.value (string) — String representation of a file.done (function done(err, node, file)).Returns
Node — The given syntax tree node.
Throws
When no node was given and no node was found on the file.
Invoked when transformation is complete.
Signatures
function done(err);function done(null, node, file).Parameters
exception (Error) — Failure;doc (string) — Document generated by the process;file (File) — File object representing the input file;Compile a syntax tree into a document.
Either a node or a file which was previously passed to processor.parse(),
must be given.
Signatures
doc = processor.stringify(node[, file|value][, options]);doc = processor.stringify(file[, options]).Parameters
node (Object) — Syntax tree as returned by parse();file (VFile) — Virtual file.value (string) — String representation of a file.options (Object) — Configuration.Returns
doc (string) — Document.
Throws
When no node was given and no node was found on the file.
Parse / Transform / Compile. When an async transformer is used,
null is returned and done must be given to receive the results
upon completion.
Signatures
doc = processor.process(file|value[, options][, done]).Parameters
file (File) — Virtual file;value (string) — String representation of a file;options (Object) — Configuration.done (function done(err?, doc?, file?)).Returns
string — Document generated by the process;
Invoked when processing is complete.
Signatures
function done(err);function done(null, doc, file).Parameters
exception (Error) — Failure;doc (string) — Document generated by the process;file (File) — File object representing the input file;FAQs
parse, inspect, transform, and serialize content through syntax trees
We found that unified demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.