Details

• Plugins configure the processors they are applied on in the following ways:
  • They change the processor: such as the parser, the compiler, or configuring data
  • They specify how to handle syntax trees and files

• Plugins are a concept. They materialize as attachers.

• Plugins can contain two parts:
  • an attacher, which is a function that is invoked when someone calls .use
  • transformer, which is an optional function invoked each time a file is processed with a syntax tree and a virtual file.

Attacher

• sig:

function attacher([options]): Transformer|undefined

• Attachers are materialized plugins. An attacher is a function that can receive options and configures the processor.

Transformer

function transformer(node, file[, next])

• if an error occurs (either because it’s thrown, returned, rejected, or passed to next), the process stops.
• params
  • next: the transformer may perform asynchronous operations, and must call next().
• return
  • void: If nothing is returned, the next transformer keeps using same tree
  • Error — Fatal error to stop the proces
  • node (Node) — New syntax tree. If returned, the next transformer is given this new tree
  • Promise — Returned to perform an asynchronous operation. The promise must be resolved (optionally with a Node) or rejected (optionally with an Error)

Quickstart

• example.js

var fs = require('fs')
var retext = require('retext')
var report = require('vfile-reporter')
var spacing = require('.')

var doc = fs.readFileSync('example.md')

retext()
  .use(spacing)
  .process(doc, function(err, file) {
    console.error(report(err || file))
  })

• index.js
  • attacher plugin

module.exports = attacher

function attacher() {
  return transformer

  function transformer(tree, file) {
  }
}

Example

Move eg

module.exports = move

function move(options) {
  var expected = (options || {}).extname

  if (!expected) {
    throw new Error('Missing `extname` in options')
  }

  return transformer

  function transformer(tree, file) {
    if (file.extname && file.extname !== expected) {
      file.extname = expected
    }
  }
}

var unified = require('unified')
var parse = require('remark-parse')
var remark2rehype = require('remark-rehype')
var stringify = require('rehype-stringify')
var vfile = require('to-vfile')
var report = require('vfile-reporter')
var move = require('./move')

unified()
  .use(parse)
  .use(remark2rehype)
  .use(move, {extname: '.html'})
  .use(stringify)
  .process(vfile.readSync('index.md'), function (err, file) {
    console.error(report(err || file))
    if (file) {
      vfile.writeSync(file) // Written to `index.html`.
    }
  })