mdast-zone

HTML comments as ranges or markers in mdast.

Installation

npm

npm install mdast-zone

Component.js

component install wooorm/mdast-zone

Bower

bower install mdast-zone

Duo

var zone = require('wooorm/mdast-zone');

UMD: globals, AMD, and CommonJS (uncompressed and compressed):

<script src="path/to/mdast.js"></script>
<script src="path/to/mdast-zone.js"></script>
<script>
  mdast.use(mdastZone);
</script>

Table of Contents

• Usage

• API

  • zone(options)

    • Marker
    • function onparse(marker) and function onstringify(marker)
    • function onrun(start, nodes, end, scope)

• License

Usage

var zone = require('mdast-zone');
var mdast = require('mdast');

Callback invoked when a range is found.

function onrun(start, nodes, end) {
    return [
        start.node,
        {
            'type': 'paragraph',
            'children': [
                {
                    'type': 'text',
                    'value': 'Bar'
                }
            ]
        },
        end.node
    ];
}

Process a document.

var doc = mdast().use(zone({
    'name': 'foo',
    'onrun': onrun
})).process(
    '<!--foo start-->\n' +
    '\n' +
    'Foo\n' +
    '\n' +
    '<!--foo end-->\n'
);

Yields:

<!--foo start-->

Bar

<!--foo end-->

API

Note that mdast-zone is not a plugin by itself. It should be used by one.

zone(options)

The goal of zone is two fold:

1. Configuration during mdasts parse and/or stringification stage, using markers;

2. Transforming parts of a document without affecting other parts, which is not visible when rendering to HTML, using ranges (a starting marker, followed by nodes, and an ending marker).

The first is exposed by this plugin in the form of an HTML comment which sort-of looks like a self-closing, custom tag. The second by placing starting and ending tags, as siblings, in a parent.

Parameters

• options (Object):

  • name (string) — Type to look for;

  • onparse (function (marker), optional) — Callback invoked when a marker is found during parsing;

  • onstringify (function (marker), optional) — Callback invoked when a marker is found during stringification;

  • onrun (Array.<Node>? = function (start, nodes, end), optional) — Callback invoked when a range is found during transformation.

Returns

Function — Should be passed to mdast.use().

Marker

Example

<!--foo bar="baz" qux-->

Yields:

{
  "type": "marker",
  "attributes": "bar=\"baz\" qux",
  "parameters": {
    "bar": "baz",
    "qux": true
  },
  "node": {
    "type": "html",
    "value": "<!--foo bar=\"baz\" qux-->"
  }
}

Fields

• type (string) — Either "marker", "start", or "end";
• attributes (string) — Raw, unparsed value;
• parameters (Object.<string, *>) — Parsed attributes;
• node (Node) — Original HTML node.

function onparse(marker) and function onstringify(marker)

Parameters

• marker (Marker) — Marker.

When passing name: "foo" and onparse: console.log.bind(console) to zone(), comments in the form of <!--foo bar="baz" qux--> are detected and onparse is invoked:

An onstringify method could (instead, or both) be passed to zone(), which would be invoked with the same marker but during the stringification phase.

function onrun(start, nodes, end, scope)

Parameters

• start (Marker) — Start of range;

• nodes (Array.<Node>) — Nodes between start and end;

• end (Marker) — End of range.

• scope (Object):

  • parent (Node) — Parent of the range;
  • start (number) — Index of start in parent;
  • end (number) — Index of end in parent.

Returns

Array.<Node>? — Zero or more nodes to replace the range (including start and ends HTML comments) with.

License

MIT © Titus Wormer