mdast-zone

mdast-zone

mdast utility to treat HTML comments as ranges.

Useful in remark plugins.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install mdast-zone

Use

Say we have the following file, example.md:

<!--foo start-->

Foo

<!--foo end-->

And our script, example.js, looks as follows:

import toVFile from 'to-vfile'
import remark from 'remark'
import {zone} from 'mdast-zone'

remark()
  .use(plugin)
  .process(toVFile.readSync('example.md'), function(err, file) {
    if (err) throw err
    console.log(String(file))
  })

function plugin() {
  return transform

  function transform(tree) {
    zone(tree, 'foo', mutate)
  }

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

Now, running node example yields:

<!--foo start-->

Bar

<!--foo end-->

API

This package exports the following identifiers: zone. There is no default export.

zone(tree, name, handler)

Search tree for comment ranges (“zones”).

Parameters

• tree (Node) — Tree to search for ranges
• name (string) — Name of ranges to search for
• handler (Function) — Function invoked for each found range

function handler(start, nodes, end)

Invoked with the two markers that determine a range: the first start and the last end, and the content inside.

Parameters

• start (Node) — Start of range (an HTML comment node)
• nodes (Array.<Node>) — Nodes between start and end
• end (Node) — End of range (an HTML comment node)

Returns

Array.<Node>? — List of nodes to replace start, nodes, and end with, optional.

Security

Improper use of handler can open you up to a cross-site scripting (XSS) attack as the value it returns is injected into the syntax tree. This can become a problem if the tree is later transformed to hast. The following example shows how a script is injected that could run when loaded in a browser.

function handler(start, nodes, end) {
  return [start, {type: 'html', value: 'alert(1)'}, end]
}

Yields:

<!--foo start-->

<script>alert(1)</script>

<!--foo end-->

Either do not use user input or use hast-util-santize.

Related

• mdast-util-heading-range — use headings as ranges instead of comments

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer