unified-engine

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.

README

unified-engine

Engine to process multiple files with unified, allowing users to configure from the file-system.

Projects

The following projects wrap the engine:

• unified-args — Create CLIs for processors
• unified-engine-gulp — Create Gulp plug-ins
• unified-engine-atom — Create Atom Linters for processors

Installation

npm:

npm install unified-engine

Usage

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
}, function (err) {
  if (err) throw err;
});

Table of Contents

• API
  • engine(options, callback)
• Plug-ins
• Configuration
• Ignoring
• License

API

engine(options, callback)

Process files according to options and invoke callback when done.

options

• processor (Processor) — Unified processor to transform files
• cwd (string, default: process.cwd()) — Directory to search files in, load plug-ins from, and more
• files (Array.<string|VFile>, optional) — Paths or globs to files and directories, or virtual files, to process
• extensions (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 given
• filePath (string, optional) — File path to process the given file on streamIn as
• streamOut (WritableStream, default: process.stdout) — Stream to write processed files to
• streamError (WritableStream, default: process.stderr) — Stream to write the report (if any) to
• out (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 to
• alwaysStringify (boolean, default: false) — Whether to always compile successfully processed files
• tree (boolean, default: false) — Whether to treat both input and output as a syntax tree
• treeIn (boolean, default: tree) — Whether to treat input as a syntax tree
• treeOut (boolean, default: tree) — Whether to treat output as a syntax tree
• rcName (string, optional) — Name of configuration files to load
• packageField (string, optional) — Property at which configuration can be found in package.json files
• detectConfig (boolean, default: whether rcName or packageField is given) — Whether to search for configuration files
• rcPath (string, optional) — File-path to a configuration file to load
• settings (Object, optional) — Configuration for the parser and compiler of the processor
• ignoreName (string, optional) — Name of ignore files to load
• detectIgnore (boolean, default: whether ignoreName is given) — Whether to search for ignore files
• ignorePath (string, optional) — File-path to an ignore file to load
• silentlyIgnore (boolean, default: false) — Skip given files if they are ignored
• plugins (Array|Object, optional) — Plug-ins to use
• pluginPrefix (string, optional) — Optional prefix to use when searching for plug-ins
• configTransform (Function, optional) — Transform config files from a different schema
• reporter (string or function, default: require('vfile-reporter')) — Reporter to use
• reporterOptions (Object?, optional) — Config to pass to the used reporter
• color (boolean, default: false) — Whether to report with ANSI colour sequences
• silent (boolean, default: false) — Report only fatal errors
• quiet (boolean, default: silent) — Do not report successful files
• frail (boolean, default: false) — Call back with an unsuccessful (1) code on warnings as well as errors

function callback(err[, 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

• err (Error) — Fatal error
• code (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 occur
• context (Object) — Processing context, containing internally used information and a files array with the processed files

Plug-ins

doc/plug-ins.md describes in detail how plug-ins 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.

License

MIT © Titus Wormer