Have ideas to improve npm?Join in the discussion! »

    mdast-zone

    4.0.1 • Public • Published

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

    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

    Install

    npm i mdast-zone

    DownloadsWeekly Downloads

    2,529

    Version

    4.0.1

    License

    MIT

    Unpacked Size

    9.33 kB

    Total Files

    4

    Last publish

    Collaborators

    • avatar
    • avatar