Details

• does 3 things
  • attacher
    • It modifies the processor: the parser, the stringifier;
  • transformer
    • It transforms the AST;
  • completer
    • It adds new files to be processed by mdast(1).

Attacher

• may return transformer

• may attach to a completer

• An attacher has access to the parser, which provides its own pluggable interface, consisting of tokenizers (see TOKENIZER) and locators (see LOCATOR).

• An attacher is the thing passed to use()

• can receive plugin specific options

• Note that mdast(1) invokes attacher for each file, not just once.

• signature

transformer? = attacher(mdast, options[, fileSet]).

/**
 * Add an extension.
 * The `processor` is the instance of mdast this attacher
 * is `use`d on.{
 * This plugin can be used as `mdast.use(plugin, {ext: 'html'})`.
 */
module.exports = function (processor, options) {
    var extension = (options || {}).ext;

    /**
     * Change a file-extension to `extension`.
     */
    function transformer(ast, file) {
        file.move({
            'extension': extension
        });
    }

    return transformer;
};

Transformer

• transformer(node, file[, next])

var visit = require('unist-util-visit');

/**
 * Add a `js` language flag to code nodes when without flag.
 */
function transformer(ast, file) {
    visit(ast, 'code', function (node) {
        if (!node.lang) {
            node.lang = 'js';
        }
    });
}

/**
 * Expose.
 * This plugin can be used as `mdast.use(plugin)`.
 */
module.exports = function () {
    return transformer;
};

Tokenizer

• function tokenizer(eat, value, silent)
• Sometimes, mainly when there is a need to introduce new syntactic entities with a certain level of precedence, interfacing with the parser is necessary.
• two types of tokenizers
  • block
  • inline
• Block-level tokenizers are the same as inline-level tokenizers, with the exception that the latter require locator functions.
• Tokenizers test whether a certain given documents starts with a certain syntactic entity
• When that occurs, they consume that token, a process which is called “eating” in mdast
• Locators enable tokenizers to function faster by providing information on the where the next entity occurs.

function mention(eat, value) {
    var match = /^@(\w+)/.exec(value);

    if (match) {
        if (silent) {
            return true;
        }

        return eat(match[0])({
            'type': 'link',
            'href': 'https://my-social-network/' + match[1],
            'children': [{
                'type': 'text',
                'value': match[0]
            }]
        });
    }
}

• example: https://github.com/remarkjs/remark-github/blob/461f1fb435b1659c914ff184029b2ba8f8b62b3f/lib/tokenizer/mention.js#L76

https://calendly.com/thence/dendron