Options

unified-engine can be configured extensively by engine authors.

options.processor
options.cwd
options.files
options.extensions
options.streamIn
options.filePath
options.streamOut
options.streamError
options.out
options.output
options.alwaysStringify
options.tree
options.treeIn
options.treeOut
options.inspect
options.rcName
options.packageField
options.detectConfig
options.rcPath
options.settings
options.ignoreName
options.detectIgnore
options.ignorePath
options.silentlyIgnore
options.plugins
options.pluginPrefix
options.defaultConfig
options.configTransform
options.reporter
options.reporterOptions
options.color
options.silent
options.quiet
options.frail

`options.processor`

Unified processor to transform files.

Type: Processor

Example

The following example reformats stdin(4) using remark, writes the report to stderr(4), and formatted document to stdout(4).

var engine = require('unified-engine')
var remark = require('remark')

engine({processor: remark}, done)

function done(err) {
  if (err) throw err
}

`options.cwd`

Directory to search files in, load plug-ins from, and more.

Type: string
Default: process.cwd()

Example

The following example reformats readme.md. The doc directory is used to process from.

var path = require('path')
var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    cwd: path.join(process.cwd(), 'doc'),
    files: ['readme.md'],
    output: true
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.files`

Paths or globs, or vfiles to files and directories to process. Fileglobs (for example, *.md) can be given to add all matching files. Directories and globs to directories can be given alongside extensions to search directories for files matching an extension (for example, dir to add dir/readme.txt and dir/sub/history.text if extensions is ['txt', 'text']). This searching will not include node_modules or hidden directories (those starting with a dot, ., like .git).

Type: Array.<string>
Default: []

Example

The following example processes README and all files with an md extension in doc.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark,
    files: ['README', 'doc'],
    extensions: ['md']
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.extensions`

If files matches directories, those directories are searched for files whose extension matches the given extensions.

In addition, if treeIn is turned on and output is true or points to a directory, generated files are given the first extension.

Type: Array.<string>
Default: []

Example

The following example reformats all files with md, markdown, and mkd extensions in the current directory.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark,
    files: ['.'],
    extensions: ['md', 'mkd', 'markdown'],
    output: true
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.streamIn`

Stream to read from if no files are found or given. If streamIn is the only possible source of input but it’s a TTY, an error is thrown.

Type: ReadableStream
Default: process.stdin

Example

The following example uses remark-lint to lint an incoming stream.

var PassThrough = require('stream').PassThrough
var engine = require('unified-engine')
var remark = require('remark')
var recommended = require('remark-preset-lint-recommended')

var streamIn = new PassThrough()

engine(
  {
    processor: remark(),
    plugins: [recommended],
    streamIn: streamIn,
    out: false
  },
  done
)

streamIn.write('doc')

setTimeout(delayed, 100)

function delayed() {
  streamIn.end('ument')
}

function done(err) {
  if (err) throw err
}

Yields:

<stdin>
  1:1  warning  Missing newline character at end of file  final-newline  remark-lint

⚠ 1 warning

`options.filePath`

File path to process the given file on streamIn as, if any.

Type: string (optional)

Example

The following example shows the same as before, with a filePath added, which is shown in the report:

var PassThrough = require('stream').PassThrough
var engine = require('unified-engine')
var remark = require('remark')
var recommended = require('remark-preset-lint-recommended')

var streamIn = new PassThrough()

engine(
  {
    processor: remark(),
    plugins: [recommended],
    filePath: '~/alpha/bravo/charlie.md',
    streamIn: streamIn,
    out: false
  },
  done
)

streamIn.write('doc')

setTimeout(function() {
  streamIn.end('ument')
}, 100)

function done(err) {
  if (err) throw err
}

Yields:

~/alpha/bravo/charlie.md
  1:1  warning  Missing newline character at end of file  final-newline  remark-lint

⚠ 1 warning

`options.streamOut`

Stream to write processed files to. This behaviour is suppressed if:

out is false
output is not false
multiple files are processed
a fatal error occurred while processing a file

Type: WritableStream
Default: process.stdout

Example

The following example reads readme.md and writes the compiled document to readme-two.md. Note that this can also be achieved by passing output: 'readme-two.md' instead of streamOut.

var fs = require('fs')
var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    streamOut: fs.createWriteStream('readme-two.md')
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.streamError`

Stream to write the report (if any) to.

Type: WritableStream
Default: process.stderr

Example

The following example uses remark-lint to lint readme.md and writes the report to report.txt.

var fs = require('fs')
var engine = require('unified-engine')
var remark = require('remark')
var recommended = require('remark-preset-lint-recommended')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    plugins: [recommended],
    out: false,
    streamErr: fs.createWriteStream('report.txt')
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.out`

Whether to write the processed file to streamOut. The default behaviour is to only write under some conditions, as specified in the section on streamOut, but if out is false nothing will be written to streamOut.

Type: boolean
Default: depends (see above)

Example

The following example uses remark-lint to lint readme.md, writes the report, and ignores the compiled document.

var engine = require('unified-engine')
var remark = require('remark')
var recommended = require('remark-preset-lint-recommended')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    plugins: [recommended],
    out: false
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.output`

Whether to write successfully processed files and where to.

When true, overwrites the given files
When false, does not write to the file-system
When pointing to an existing directory, files are written to that directory and keep their original basenames
When the parent directory of the given path exists and one file is processed, the file is written to the given path
Otherwise, a fatal error is thrown

Note that if treeIn is turned on, generated files get the first defined extensions. If treeOut is turned on, generated files receive the 'json' extension. If inspect is turned on, generated files receive the 'txt' extension.

Type: string or boolean
Default: false

Example

The following example writes all files in src/ with an md extension, compiled, to dest/.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['src/'],
    extensions: ['md'],
    output: 'dest/'
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.alwaysStringify`

Whether to always stringify successful documents. By default, documents are stringified when it’s detected that a file is to be written to stdout(4) or the file system. If files are handled and possibly written somewhere later, set this option to true.

Type: boolean
Default: false

`options.tree`

Whether to treat both input and output as a syntax tree. If given, specifies the default value for both treeIn and treeOut.

Type: boolean, optional
Default: false

Example

The following example reads tree.json, then remark-unlink transforms the syntax tree, and the transformed tree is written to stdout(4).

var engine = require('unified-engine')
var remark = require('remark')
var unlink = require('remark-unlink')

engine(
  {
    processor: remark(),
    plugins: [unlink],
    files: ['tree.json'],
    tree: true
  },
  done
)

function done(err) {
  if (err) throw err
}

Where tree.json looks as follows:

{
  "type": "paragraph",
  "children": [{
    "type": "link",
    "url": "https://example.com",
    "children": [{
      "type": "text",
      "value": "foo"
    }]
  }]
}

Yields:

{
  "type": "paragraph",
  "children": [{
    "type": "text",
    "value": "foo"
  }]
}

`options.treeIn`

Treat input as a JSON.stringifyd syntax tree, thus skipping the parsing phase and passing the syntax tree right through to transformers.

If extensions are given, sets the extension of processed files to the first one.

Type: boolean, optional
Default: options.tree

Example

The following example reads tree.json, then remark-unlink transforms the syntax tree, the tree is compiled, and the resulting document is written to stdout(4).

var engine = require('unified-engine')
var remark = require('remark')
var unlink = require('remark-unlink')

engine(
  {
    processor: remark(),
    plugins: [unlink],
    files: ['tree.json'],
    treeIn: true
  },
  done
)

function done(err) {
  if (err) throw err
}

Where tree.json looks as follows:

{
  "type": "paragraph",
  "children": [{
    "type": "link",
    "url": "https://example.com",
    "children": [{
      "type": "text",
      "value": "foo"
    }]
  }]
}

Yields:

foo

`options.treeOut`

Skip the compilation phase and compile the transformed syntax tree to JSON.

Sets the extension of processed files to json, if possible.

Type: boolean, optional
Default: options.tree

Example

The following example shows a script which reads and parses doc.md, then remark-unlink transforms the syntax tree, and the tree is written to stdout(4).

var engine = require('unified-engine')
var remark = require('remark')
var unlink = require('remark-unlink')

engine(
  {
    processor: remark(),
    plugins: [unlink],
    files: ['doc.md'],
    treeOut: true
  },
  done
)

function done(err) {
  if (err) throw err
}

Where doc.md looks as follows:

[foo](https://example.com)

Yields:

{
  "type": "paragraph",
  "children": [{
    "type": "text",
    "value": "foo"
  }]
}

`options.inspect`

Skip the compilation phase and output a syntax tree formatted with unist-util-inspect.

Sets the extension of processed files to txt if possible.

Uses ANSI colour sequences in the formatted syntax tree if color is turned on.

Type: boolean, optional
Default: false

Example

The following example shows a script which reads and parses doc.md, then remark-unlink transforms the syntax tree, the tree is formatted with unist-util-inspect, and finally written to stdout(4).

var engine = require('unified-engine')
var remark = require('remark')
var unlink = require('remark-unlink')

engine(
  {
    processor: remark(),
    plugins: [unlink],
    files: ['doc.md'],
    inspect: true
  },
  done
)

function done(err) {
  if (err) throw err
}

Where doc.md looks as follows:

[foo](https://example.com)

Yields:

root[1] (1:1-2:1, 0-27)
└─ paragraph[1] (1:1-1:27, 0-26)
   └─ text: "foo" (1:2-1:5, 1-4)

`options.rcName`

Name of configuration file to load. If given and detectConfig is not false, $rcName files are loaded and parsed as JSON, $rcName.js are required, and $rcName.yml and $rcName.yaml are loaded with js-yaml (safeLoad).

Type: string, optional

Example

The following example processes readme.md, and allows configuration from .remarkrc, .remarkrc.js, and .remarkrc.yaml files.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    rcName: '.remarkrc',
    files: ['readme.md']
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.packageField`

Property at which configuration can live in package.json files. If given and detectConfig is not false, package.json files are loaded and parsed as JSON and their $packageField property is used for configuration.

Type: string, optional

Example

The following example processes readme.md, and allows configuration from remarkConfig fields in package.json files.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    packageField: 'remarkConfig',
    files: ['readme.md']
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.detectConfig`

Whether to search for configuration files ($rcName, $rcName.js, $rcName.yaml, and package.json with $packageField).

Type: boolean, optional
Default: true if rcName or packageField are given

Example

The following example processes readme.md but does not allow configuration from .remarkrc or package.json files, as detectConfig is false.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    detectConfig: false,
    rcName: '.remarkrc',
    packageField: 'remarkConfig',
    files: ['readme.md']
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.rcPath`

File-path to a config file to load, regardless of detectConfig or rcName.

If the file’s extension is yml or yaml, it’s loaded as YAML. If the file’s extension is js, it’s required. If the file’s basename is package.json, the property at packageField is used. Otherwise, the file is parsed as JSON.

Type: string, optional

Example

The following example processes readme.md and loads configuration from config.json.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    rcPath: 'config.json',
    files: ['readme.md']
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.settings`

Configuration for the parser and compiler of the processor.

Type: Object, optional

Example

The following example processes readme.md and configures the parser and compiler with position: false.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    settings: {position: false}
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.ignoreName`

Name of ignore file to load. If given and detectIgnore is not false, $ignoreName files are loaded.

Type: string, optional

Example

The following example processes files in the current working directory with an md extension, and is configured to ignore file paths from the closest .remarkignore file.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['.'],
    extensions: ['md'],
    ignoreName: '.remarkignore'
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.detectIgnore`

Whether to search for ignore files ($ignoreName).

Type: boolean, optional
Default: true if ignoreName is given

Example

The following example processes files in the current working directory with an md extension but does not ignore file paths from the closest .remarkignore file, because detectIgnore is false.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['.'],
    extensions: ['md'],
    ignoreName: '.remarkignore',
    detectIgnore: false
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.ignorePath`

File-path to ignore file to load, regardless of detectIgnore or ignoreName.

Type: string, optional

Example

The following example processes files in the current working directory with an md extension and ignores file paths specified in .gitignore.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['.'],
    extensions: ['md'],
    ignorePath: '.gitignore'
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.silentlyIgnore`

Skip given files which are ignored by ignore files, instead of warning about them.

Type: boolean, default: false

`options.plugins`

Plug-ins to load and attach with options to the processor for every processed file.

Type: Object, Array, optional. Same format as plugins in config files

Example

The following example processes readme.md and loads the remark-preset-lint-recommended plug-in.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    plugins: ['remark-preset-lint-recommended']
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.pluginPrefix`

Allow plug-ins to be specified without a prefix. For example, if a plug-in is specified with a name of foo, and pluginPrefix is bar, both bar-foo and foo are checked in node_modules/ directories.

Note: If a prefix is specified, plug-ins with that prefix are preferred over plug-ins without that prefix.

Type: string, optional

Example

The following example processes readme.md and loads the preset-lint-recommended plug-in. Because pluginPrefix is given, this resolves to remark-preset-lint-recommended from node_modules/ if available.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    pluginPrefix: 'remark',
    plugins: ['preset-lint-recommended']
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.defaultConfig`

Optional object with plugins and/or settings to use if no config file is supplied by the user.

Type: Object, optional

Example

The following example processes readme.md. If package.json exists, that config is used, otherwise the configuration at defaultConfig is used.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    packageField: 'remarkConfig',
    defaultConfig: {settings: {commonmark: true}}
  },
  done
)

function done(err) {
  if (err) throw err
}

Where package.json contains:

{
  "name": "foo",
  "private": true,
  "remarkConfig": {
    "settings": {
      "footnotes": true
    }
  }
}

`options.configTransform`

Want configuration files in a different format? Pass a configTransform function. It will be invoked with the parsed value from configuration files and the file-path to the found file, and should return a config object (with plugins and/or settings).

Type: Function, optional

Example

The following example processes readme.md and loads options from custom (from a package.json). configTransform is invoked with those options and transforms it to configuration unified-engine understands.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    packageField: 'custom',
    configTransform: configTransform
  },
  done
)

function done(err) {
  if (err) throw err
}

function configTransform(config) {
  return {settings: (config || {}).options}
}

Where package.json contains:

{
  "name": "foo",
  "private": true,
  "custom": {
    "options": {
      "position": false
    }
  }
}

`options.reporter`

Reporter to use. Reporters must be loadable from the cwd (such as by installing them from that directory with npm). Reporters must be VFile reporters.

Type: string or function, optional, default: require('vfile-reporter'). If string, the reporter’s prefix (vfile-reporter-) can be omitted, so if json is given, vfile-reporter-json is loaded if it exists, and otherwise the json module itself is loaded (which in this example won’t work as it’s not a reporter)

Note

The quiet, silent, and color options may not work with the used reporter.

Example

The following example processes all HTML files in the current directory with rehype, configures the processor with .rehyperc files, and prints a report in json, with reporter options.

var engine = require('unified-engine')
var rehype = require('rehype')

engine(
  {
    processor: rehype(),
    files: ['.'],
    extensions: ['html'],
    rcName: '.rehyperc',
    reporter: 'json',
    reporterOptions: {pretty: true}
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.reporterOptions`

Options to pass to the reporter.

Type: Object, optional

Note

The quiet, silent, and color options are preferred over reporterOptions (and passed too).

Example

See options.reporter for an example.

`options.color`

Whether to report or inspect with ANSI colour sequences.

Type: boolean, default: false

Note

This option may not work with the used reporter.

Example

The following example processes readme.md and uses colour in the report.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    color: true,
    out: false
  },
  done
)

function done(err) {
  if (err) throw err
}

Yields:

�[4m�[32mreadme.md�[39m�[24m: no issues found

`options.silent`

Show only fatal errors in the report.

Type: boolean, default: false

Note

This option may not work with the used reporter.

Example

The following example uses remark-lint to lint readme.md but does not report any warnings or success messages, only fatal errors, if they occur.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    plugins: ['remark-preset-lint-recommended'],
    silent: true
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.quiet`

Whether to ignore processed files without any messages in the report. The default behaviour is to show a success message.

Type: boolean, default: options.silent

Note

This option may not work with the used reporter.

Example

The following example uses remark-lint to lint readme.md. Nothing is reported if the file processed successfully.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    plugins: ['remark-preset-lint-recommended'],
    quiet: true
  },
  done
)

function done(err) {
  if (err) throw err
}

`options.frail`

Count warnings as errors when calculating if the process succeeded.

Type: boolean, default: false

Example

The following example uses remark-lint to lint readme.md and logs the exit code. Normally, only errors turn the code to 1, but in frail mode lint warnings result in the same.

var engine = require('unified-engine')
var remark = require('remark')

engine(
  {
    processor: remark(),
    files: ['readme.md'],
    plugins: ['remark-preset-lint-recommended'],
    frail: true
  },
  done
)

function done(err, code) {
  process.exit(err ? 1 : code)
}

Uh oh!

FilesExpand file tree

options.md

Latest commit

History

options.md

File metadata and controls

Options

Table of Contents

options.processor

Example

options.cwd

Example

options.files

Example

options.extensions

Example

options.streamIn

Example

options.filePath

Example

options.streamOut

Example

options.streamError

Example

options.out

Example

options.output

Example

options.alwaysStringify

options.tree

Example

options.treeIn

Example

options.treeOut

Example

options.inspect

Example

options.rcName

Example

options.packageField

Example

options.detectConfig

Example

options.rcPath

Example

options.settings

Example

options.ignoreName

Example

options.detectIgnore

Example

options.ignorePath

Example

options.silentlyIgnore

options.plugins

Example

options.pluginPrefix

Example

options.defaultConfig

Example

options.configTransform

Example

options.reporter

Note

Example

options.reporterOptions

Note

Example

options.color

Note

Example

options.silent

Note

Example

options.quiet

Note

Example

options.frail

Example

`options.processor`

`options.cwd`

`options.files`

`options.extensions`

`options.streamIn`

`options.filePath`

`options.streamOut`

`options.streamError`

`options.out`

`options.output`

`options.alwaysStringify`

`options.tree`

`options.treeIn`

`options.treeOut`

`options.inspect`

`options.rcName`

`options.packageField`

`options.detectConfig`

`options.rcPath`

`options.settings`

`options.ignoreName`

`options.detectIgnore`

`options.ignorePath`

`options.silentlyIgnore`

`options.plugins`

`options.pluginPrefix`

`options.defaultConfig`

`options.configTransform`

`options.reporter`

`options.reporterOptions`

`options.color`

`options.silent`

`options.quiet`

`options.frail`