Awesome
mdast-util-heading-range
mdast utility to find headings and replace the content in their section.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Types
- Compatibility
- Security
- Related
- Contribute
- License
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 by remark-toc
to update the
above Contents
heading.
A similar package, mdast-zone
, does the same but uses comments
to mark the start and end of sections.
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install mdast-util-heading-range
In Deno with esm.sh
:
import {headingRange} from 'https://esm.sh/mdast-util-heading-range@4'
In browsers with esm.sh
:
<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 identifier headingRange
.
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
(Node
) — tree to changetest
(Test
) — same as passing{test: Test}
options
(Options
) — configurationhandler
(Handler
) — handle a section
Returns
Nothing (undefined
).
Handler
Callback called when a section is found (TypeScript type).
Parameters
start
(Heading
) — start of section (a heading node matchingtest
)nodes
(Array<Node>
) — nodes betweenstart
andend
end
(Node
orundefined
) — end of section, if anyinfo
(Info
) — 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
(Node
) — parent of the sectionstart
(number
) — index ofstart
inparent
end
(number
orundefined
) — index ofend
inparent
Options
Configuration (TypeScript type).
Fields
test
(Test
) — test for a headingignoreFinalDefinitions
(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 headingnode
(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 types Handler
,
Info
, Options
, Test
,
and TestFunction
.
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 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.
/** @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
.
Related
mdast-zone
— similar but uses comments to mark the start and end of sections
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, organisation, or community you agree to abide by its terms.