unified

Project: syntax-tree/mdast-util-heading-range

Package: mdast-util-heading-range@3.0.0

  1. Dependencies: 0·Dependents: 21
  2. mdast utility to use headings as ranges in mdast
  1. markdown 141
  2. util 137
  3. utility 133
  4. unist 121
  5. mdast 90
  6. mdast-util 30
  7. heading 26
  8. range 2

mdast-util-heading-range

Build Coverage Downloads Size Sponsors Backers Chat

mdast utility to use headings as ranges.

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-util-heading-range

Use

Say we have the following file, example.md:

# Foo

Bar.

# Baz

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

import toVFile from 'to-vfile'
import remark from 'remark'
import {headingRange} from 'mdast-util-heading-range'

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) {
    headingRange(tree, 'foo', handler)
  }

  function handler(start, nodes, end) {
    return [
      start,
      {type: 'paragraph', children: [{type: 'text', value: 'Qux.'}]},
      end
    ]
  }
}

Now, running node example yields:

# Foo

Qux.

# Baz

API

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

headingRange(tree, test|options, handler)

Search tree (Node) and transform a section without affecting other parts with handler (Function). A “section” is a heading that passes test, until the next heading of the same or lower depth, or the end of the document. If ignoreFinalDefinitions: true, final definitions “in” the section are excluded.

options
options.test

Heading to look for (string, RegExp, Function). When string, wrapped in new RegExp('^(' + value + ')$', 'i'); when RegExp, wrapped in function (value) {expression.test(value)}

options.ignoreFinalDefinitions

Ignore final definitions otherwise in the section (boolean, default: false).

function test(value, node)

Function invoked for each heading with its content (string) and node itself (Heading) to check if it’s the one to look for.

Returns

Boolean?, true if this is the heading to use.

function handler(start, nodes, end?, scope)

Callback invoked when a range is found.

Parameters
start

Start of range (Heading).

nodes

Nodes between start and end (Array.<Node>).

end

End of range, if any (Node?).

scope

Extra info (Object):

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

<script>alert(1)</script>

# Baz

Either do not use user input in handler 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