Security News
Highlights from the 2024 Rails Community Survey
A record 2,709 developers participated in the 2024 Ruby on Rails Community Survey, revealing key tools, practices, and trends shaping the Rails ecosystem.
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 remark, retext, and hast.
npm:
npm install unified
unified is also available as an AMD, CommonJS, and globals module, uncompressed and compressed.
From remark:
var unified = require('unified');
var Parser = require('./lib/parse.js');
var Compiler = require('./lib/stringify.js');
module.exports = unified({
'name': 'mdast',
'Parser': Parser,
'Compiler': Compiler
});
remark — Markdown processor powered by plugins.
retext — Extensible system for analysing and manipulating natural language.
hast — HTML processor powered by plugins.
Bridges are a concept which support two-way transformation between processors. See unified-bridge for more information.
unified(options)
Create a new Processor
constructor.
Parameters — options
(Object
):
name
(string
) — Unique namespace, e.g. 'mdast'
or 'retext'
.
data
(Object
, optional) — JSON.stringify
able dictionary providing
information to Parser
, Compiler
, and plug-ins.
Parser
(Function
) — Constructor which transforms a virtual file
into a syntax tree. When input is parsed, this function will be
constructed with a file
, settings
, and the processor. Parser
instances must 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
, settings
, and the processor. Compiler
instances must have a compile
method which returns a string
.
The syntax tree representation of a file can be accessed by executing
file.namespace(name).tree
.
Returns — Function
(Processor
constructor).
Processor([processor])
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
.
processor.Parser
processor.Compiler
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.
Parser
s must have a parse
method, Compiler
s a compile
method.
Processor#use(plugin[, input...])
Change the way the processor works by using a plugin.
Signatures
processor.use(plugin[, input...])
;processor.use(plugins[, input...])
;processor.use(list)
;processor.use(matrix)
.Parameters
plugin
(Function
) — Plugin.
plugins
(Array.<Function>
) — List of plugins.
list
(Array
) — List where the first value is a plugin
,
and further values are input
;
matrix
(Array
) — Matrix where each entry is a list
.
input
(*
) — Passed to plugin. Specified by its documentation.
Returns
Processor
— this
(the context object).
Plugin
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”.
function attacher(processor[, input...])
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 use
d, 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 use
d;input
(*
) — Passed by the user of a plug-in.Returns
transformer
(optional).
function transformer(node, file[, next])
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.
Processor#parse(file[, options])
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
).
Processor#run(node[, file][, done])
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.
function done(err, node, 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;Processor#stringify(node[, file][, options])
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.
Processor#process(file[, options][, done])
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;
function done(err, doc, file)
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;Processor#data
JSON.stringify
able dictionary providing information to Parser
, Compiler
,
and plug-ins. Cloned when a Processor
is constructed and to processor.data
.
Type: Object
, optional.
FAQs
parse, inspect, transform, and serialize content through syntax trees
The npm package unified receives a total of 6,563,986 weekly downloads. As such, unified popularity was classified as popular.
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
A record 2,709 developers participated in the 2024 Ruby on Rails Community Survey, revealing key tools, practices, and trends shaping the Rails ecosystem.
Security News
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.