What is unified-engine?
The unified-engine is a powerful tool for processing text using plugins. It is part of the unified collective, which is a project that provides a suite of tools for working with content as structured data. The engine allows you to read, process, and write files using a pipeline of plugins, making it highly extensible and customizable.
What are unified-engine's main functionalities?
Reading Files
This feature allows you to read files from the filesystem. In this example, the engine reads a Markdown file using the 'remark-parse' plugin.
const engine = require('unified-engine');
const vfile = require('to-vfile');
engine({
files: ['example.md'],
processor: unified().use(require('remark-parse')),
cwd: process.cwd(),
extensions: ['md'],
output: false
}, (err, status) => {
if (err) throw err;
console.log('Files read successfully');
});
Processing Files
This feature allows you to process files using a pipeline of plugins. In this example, the engine processes a Markdown file and converts it to HTML using 'remark-parse' and 'remark-html' plugins.
const engine = require('unified-engine');
const unified = require('unified');
const markdown = require('remark-parse');
const html = require('remark-html');
engine({
files: ['example.md'],
processor: unified().use(markdown).use(html),
cwd: process.cwd(),
extensions: ['md'],
output: 'example.html'
}, (err, status) => {
if (err) throw err;
console.log('Files processed successfully');
});
Writing Files
This feature allows you to write processed files back to the filesystem. In this example, the engine writes the processed HTML output to 'example.html'.
const engine = require('unified-engine');
const vfile = require('to-vfile');
const unified = require('unified');
const markdown = require('remark-parse');
const html = require('remark-html');
engine({
files: ['example.md'],
processor: unified().use(markdown).use(html),
cwd: process.cwd(),
extensions: ['md'],
output: 'example.html'
}, (err, status) => {
if (err) throw err;
console.log('Files written successfully');
});
Other packages similar to unified-engine
gulp
Gulp is a toolkit for automating painful or time-consuming tasks in your development workflow. It uses a code-over-configuration approach and is highly extensible with plugins. Compared to unified-engine, Gulp is more general-purpose and can handle a wider range of tasks beyond text processing.
webpack
Webpack is a module bundler primarily for JavaScript, but it can transform front-end assets like HTML, CSS, and images if the corresponding loaders are used. While unified-engine focuses on processing text files using plugins, Webpack is more about bundling and optimizing assets for web applications.
broccoli
Broccoli is a fast, reliable asset pipeline, supporting constant-time rebuilds and compact build definitions. It is similar to Gulp but focuses more on the build pipeline for front-end assets. Compared to unified-engine, Broccoli is more specialized in asset management and build processes.
unified-engine
![Chat](https://img.shields.io/badge/chat-discussions-success.svg)
Engine to process multiple files with unified, allowing users to
configure from the file system.
Projects
The following projects wrap the engine:
Install
npm:
npm install unified-engine
Use
The following example processes all files in the current directory with a
Markdown extension with remark, allows configuration
from .remarkrc
and package.json
files, ignoring files from .remarkignore
files, and more.
var engine = require('unified-engine')
var remark = require('remark')
engine(
{
processor: remark,
files: ['.'],
extensions: ['md', 'markdown', 'mkd', 'mkdn', 'mkdown'],
pluginPrefix: 'remark',
rcName: '.remarkrc',
packageField: 'remarkConfig',
ignoreName: '.remarkignore',
color: true
},
done
)
function done(error) {
if (error) throw error
}
Contents
API
engine(options, callback)
Process files according to options
and invoke callback
when
done.
processor
(Processor
)
— unified processor to transform filescwd
(string
, default: process.cwd()
)
— Directory to search files in, load plugins from, and morefiles
(Array.<string|VFile>
, optional)
— Paths or globs to files and directories, or virtual files, to processextensions
(Array.<string>
, optional)
— If files
matches directories, include files with extensions
streamIn
(ReadableStream
, default: process.stdin
)
— Stream to read from if no files are found or givenfilePath
(string
, optional)
— File path to process the given file on streamIn
asstreamOut
(WritableStream
, default: process.stdout
)
— Stream to write processed files tostreamError
(WritableStream
, default: process.stderr
)
— Stream to write the report (if any) toout
(boolean
, default: depends)
— Whether to write the processed file to streamOut
output
(boolean
or string
, default: false
)
— Whether to write successfully processed files, and where toalwaysStringify
(boolean
, default: false
)
— Whether to always serialize successfully processed filestree
(boolean
, default: false
)
— Whether to treat both input and output as a syntax treetreeIn
(boolean
, default: tree
)
— Whether to treat input as a syntax treetreeOut
(boolean
, default: tree
)
— Whether to treat output as a syntax treeinspect
(boolean
, default: false
)
— Whether to output a formatted syntax treercName
(string
, optional)
— Name of configuration files to loadpackageField
(string
, optional)
— Property at which configuration can be found in package.json
filesdetectConfig
(boolean
, default: whether rcName
or
packageField
is given)
— Whether to search for configuration filesrcPath
(string
, optional)
— Filepath to a configuration file to loadsettings
(Object
, optional)
— Configuration for the parser and compiler of the processorignoreName
(string
, optional)
— Name of ignore files to loaddetectIgnore
(boolean
, default: whether ignoreName
is given)
— Whether to search for ignore filesignorePath
(string
, optional)
— Filepath to an ignore file to loadignorePathResolveFrom
('dir'
or 'cwd'
,
default: 'dir'
)
— Resolve patterns in ignorePath
from the current working directory or the
file’s directoryignorePatterns
(Array.<string>
, optional)
— Patterns to ignore in addition to ignore files, if anysilentlyIgnore
(boolean
, default: false
)
— Skip given files if they are ignoredplugins
(Array|Object
, optional)
— Plugins to usepluginPrefix
(string
, optional)
— Optional prefix to use when searching for pluginsconfigTransform
(Function
, optional)
— Transform config files from a different schemareporter
(string
or function
, default:
require('vfile-reporter')
)
— Reporter to usereporterOptions
(Object?
, optional)
— Config to pass to the used reportercolor
(boolean
, default: false
)
— Whether to report with ANSI color sequencessilent
(boolean
, default: false
)
— Report only fatal errorsquiet
(boolean
, default: silent
)
— Do not report successful filesfrail
(boolean
, default: false
)
— Call back with an unsuccessful (1
) code on warnings as well as errors
function callback(error[, code, context])
Callback invoked when processing according to options
is complete.
Invoked with either a fatal error if processing went horribly wrong (probably
due to incorrect configuration), or a status code and the processing context.
Parameters
error
(Error
) — Fatal errorcode
(number
) — Either 0
if successful, or 1
if unsuccessful.
The latter occurs if fatal errors happen when processing individual
files, or if frail
is set and warnings occurcontext
(Object
) — Processing context, containing internally used
information and a files
array with the processed files
Plugins
doc/plugins.md
describes in detail how plugins can add more files
to be processed and handle all transformed files.
Configuration
doc/configure.md
describes in detail how configuration files
work.
Ignoring
doc/ignore.md
describes in detail how ignore files work.
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.
License
MIT © Titus Wormer