mdast-util-heading-range
mdast utility to use headings as ranges.
Install
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:
var vfile = require('to-vfile')
var remark = require('remark')
var heading = require('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) {
heading(tree, 'foo', mutate)
}
function mutate(start, nodes, end) {
return [
start,
{type: 'paragraph', children: [{type: 'text', value: 'Qux.'}]},
end
]
}
}
Now, running node example
yields:
# Foo
Qux.
# Baz
API
heading(tree, test|options, onrun)
Search tree
(Node
) and transform a section without affecting other
parts with onrun
(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 onrun(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
):
parent
(Node
) — Parent of the rangestart
(number
) — Index of start
in parent
end
(number?
) — Index of end
in parent
Security
Improper use of onrun
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 onrun(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 onrun
or use hast-util-santize
.
Related
mdast-zone
— comments as ranges or markers instead of headings
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