REMARK(3)

NAME
remark - Markdown processor

SYNOPSIS

    // Load dependencies:
    var remark  require('./index.js');
    var html  require('remark-html');
    var yamlConfig  require('remark-yaml-config');
    // Use plugins:
    var processor  remark().use(yamlConfig).use(html);
    // Process the document:
    var doc  processor.process([
        '---',
        'remark:',
        '  commonmark: true',
        '---',
        '',
        '2) Some *emphasis*, **strongness**, and `code`.'
    ].join('\n'));

DESCRIPTION

These are the docs for the application programming interface of remark. To find documentation for the command line interface, see remark(1).

REMARK.USE(PLUGIN, OPTIONS)

Change the way remark works by using a plugin. Plugins are documented at on GitHub.

Signatures

    •   processor remark.use(plugin[, options]);

    •   processor remark.use(plugins).

Parameters

    •   plugin (Function) — Plugin.

    •   plugins (Array.<Function>) — List of plugins.

    •   options (Object?) — Passed to plugin. Specified by its documentation.

Returns

Object — An instance of Remark. The instance functions just like the remark object itself (it has the same methods), but caches the used plugins.

REMARK.PARSE(FILE, OPTIONS)

Parse a markdown document into an mdast node.

Signatures

    •   node remark.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 — Node. Nodes are documented at mdast.

REMARK.RUN(NODE, FILE, DONE)

Transform a node by applying plug-ins to it. Either a node or a file which was previously passed to parse(), must be given.

Signatures

    •   node remark.run(node[, file|value][, done]);

    •   node remark.run(file[, done]).

Parameters

    •   node (Object) — Node as returned by parse(), see mdast;

    •   file (VFile) — Virtual file;

    •   value (string) — String representation of a file;

    •   done (function done(err, node, file)) — See FUNCTION DONE(ERR, NODE, FILE).

Returns

Node — The given 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

    •   err (Error) — Failure;

    •   node (Node) — Transformed node;

    •   file (File) — File object representing the input file;

REMARK.STRINGIFY(NODE, FILE, OPTIONS)

Compile a node into a document.

Signatures

    •   doc remark.stringify(node[, file|value][, options]);

    •   doc remark.stringify(file[, options]).

Parameters

    •   node (Object) — Node as returned by parse(), see mdast;

    •   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.

REMARK.PROCESS(FILE, OPTIONS, DONE)

Parse, transform, and compile markdown into something else.

Signatures

    •   doc? remark.process(file|value[, options][, done]).

Parameters

    •   file (File) — Virtual file;

    •   value (string) — Source of a (virtual) file;

    •   options (Object) — Settings. See remarksetting(7);

    •   done (function done(err?, doc?, file?).

Returns

string? — Document. Formatted in markdown by default, or in whatever a asynchronous generates. When an async transformer is used, null is returned and done must be given to receive the results upon completion.

  function done(err[, doc[, file]])

Invoked when processing is complete.

Signatures

    •   function done(err);

    •   function done(null, doc, file).

Parameters

    •   err (Error) — Failure;

    •   doc (string) — Document generated by the process;

    •   file (File) — File object representing the input file;

FILESET()

remark(1) compiles multiple files using a FileSet instance. This set is exposed to plug-ins as an argument to the attacher. FileSets should not be created by plug-ins.

FILESET.VALUEOF()

FILESET.TOJSON()

Get access to the file objects in a set.

Signatures

    •   files fileSet.valueOf().

Returns

Array.<File> — List of files being processed by remark(1).

FILESET.USE(COMPLETER)

Add a completer to the middleware pipeline of a file-set. When all files are transformed, this pipeline is run and completer is invoked with fileSet.

Signatures

    •   fileSet.use(completer).

Parameters

    •   completer (Function).

FILESET.ADD(FILE FILEPATH)

Add a new file to be processed by remark(1). The given file is processed just like other files, with a few differences.

Programmatically added files are:

    •   Ignored when their file-path is already added;

    •   Never written to the file-system;

    •   Not logged about.

Signatures

    •   fileSet.use(filePath);

    •   fileSet.use(file).

Parameters

    •   filePath (string) - Path to virtual file;

    •   file (File) - Virtual file.

BUGS

⟨https://github.com/wooorm/remark/issues⟩

SEE ALSO

remark(1), remarkconfig(7), remarksetting(7)

NOTES

See also ⟨https://github.com/wooorm/mdast⟩.