unified

Project: syntax-tree/mdast-zone

Package: mdast-zone@4.0.0

  1. Dependencies: 2·Dependents: 8
  2. mdast utility to treat HTML comments as ranges or markers
  1. util 118
  2. utility 114
  3. unist 110
  4. html 110
  5. mdast 81
  6. mdast-util 24
  7. marker 12
  8. comment 7
  9. range 2

mdast-zone

Build Coverage Downloads Size Sponsors Backers Chat

mdast utility to treat HTML comments as ranges.

Useful in remark plugins.

Install

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:

var vfile = require('to-vfile')
var remark = require('remark')
var zone = require('mdast-zone')

remark()
  .use(plugin)
  .process(vfile.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

zone(tree, name, handler)

Search tree for comment ranges (“zones”).

Parameters

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

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