mdast-util-heading-range
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatmdast utility to find headings and replace the content in their section.
Contents
* [`headingRange(tree, test|options, handler)`](#headingrangetree-testoptions-handler)
* [`Handler`](#handler)
* [`Info`](#info)
* [`Options`](#options)
* [`Test`](#test)
* [`TestFunction`](#testfunction)
What is this?
This package is a utility that lets you find a certain heading, then takes the content in their section (from it to the next heading of the same or lower depth), and calls a given handler with the result, so that you can change or replace things.When should I use this?
This utility is typically useful when you have certain sections that can be generated. For example, this utility is used byremark-toc
remark-toc to update the
above Contents
heading.A similar package,
mdast-zone
mdast-zone, does the same but uses comments
to mark the start and end of sections.Install
This package is ESM onlyesm. In Node.js (version 16+), install with npm:npm install mdast-util-heading-range
In Deno with
esm.sh
esmsh:import {headingRange} from 'https://esm.sh/mdast-util-heading-range@4'
In browsers with
esm.sh
esmsh:<script type="module">
import {headingRange} from 'https://esm.sh/mdast-util-heading-range@4?bundle'
</script>
Use
Say we have the following file,example.md
:# Foo
Bar.
# Baz
…and a module
example.js
:import {read} from 'to-vfile'
import {remark} from 'remark'
import {headingRange} from 'mdast-util-heading-range'
const file = await remark()
.use(myPluginThatReplacesFoo)
.process(await read('example.md'))
console.log(String(file))
/** @type {import('unified').Plugin<[], import('mdast').Root>} */
function myPluginThatReplacesFoo() {
return function (tree) {
headingRange(tree, 'foo', function (start, nodes, end) {
return [
start,
{type: 'paragraph', children: [{type: 'text', value: 'Qux.'}]},
end
]
})
}
}
…now running
node example.js
yields:# Foo
Qux.
# Baz
API
This package exports the identifierheadingRange
api-heading-range.
There is no default export.headingRange(tree, test|options, handler)
Search tree
for a heading matching test
and change its “section” with
handler
.A “section” ranges from the matched heading 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.Parameters
— tree to change
— same as passing `{test: Test}`
options
(Options
api-options)
— configuration
handler
(Handler
api-handler)
— handle a section
Returns
Nothing (undefined
).Handler
Callback called when a section is found (TypeScript type).Parameters
— start of section (a heading node matching `test`)
nodes
(Array<Node>
node)
— nodes between `start` and `end`
— end of section, if any
— extra info
Returns
Results (Array<Node | null | undefined>
, optional).If nothing is returned, nothing will be changed. If an array of nodes (can include
null
and undefined
) is returned, the
original section will be replaced by those nodes.Info
Extra info (TypeScript type).Fields
— parent of the section
start
(number
)
— index of `start` in `parent`
end
(number
orundefined
)
— index of `end` in `parent`
Options
Configuration (TypeScript type).Fields
— test for a heading
ignoreFinalDefinitions
(boolean
, default:false
)
— ignore final definitions otherwise in the section
Test
Test for a heading (TypeScript type).When
string
, wrapped in new RegExp('^(' + value + ')$', 'i')
;
when RegExp
, wrapped in (value) => expression.test(value)
Type
export type Test = RegExp | TestFunction | string
TestFunction
Check if a node matches (TypeScript type).Parameters
value
(string
)
— plain-text heading
— heading node
Returns
Whether this is the heading that is searched for (boolean
, optional).Types
This package is fully typed with TypeScript. This package exports the typesHandler
api-handler,
Info
api-info, Options
api-options, Test
api-test,
and TestFunction
api-test-function.Compatibility
Projects maintained by the unified collective are compatible with maintained versions of Node.js.When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line,
mdast-util-heading-range@^4
, compatible with Node.js 16.Security
Improper use ofhandler
can open you up to a cross-site scripting (XSS)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 hasthast.
The following example shows how a script is injected that could run when loaded
in a browser./** @type {import('mdast-util-heading-range').Handler} */
function handler(start, nodes, end) {
return [start, {type: 'html', value: '<script>alert(1)</script>'}, end]
}
Yields:
# Foo
<script>alert(1)</script>
# Baz
Either do not use user input in
handler
or use
hast-util-santize
hast-util-sanitize.Related
— similar but uses comments to mark the start and end of sections
Contribute
Seecontributing.md
contributing in syntax-tree/.github
health for
ways to get started.
See support.md
support for ways to get help.This project has a code of conductcoc. By interacting with this repository, organisation, or community you agree to abide by its terms.