mdast-zone
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatmdast utility to find two comments and replace the content in them.
Contents
zone(tree, name, handler)
Handler
Info
What is this?
This package is a utility that lets you find certain comments, then takes the content between them, 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. Comments are a hidden part of markdown, so they can be used as processing instructions. You can use those comments to define what content to change or replace.A similar package,
mdast-util-heading-range
mdast-util-heading-range, does
the same but uses a heading 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-zone
In Deno with
esm.sh
esmsh:import {zone} from 'https://esm.sh/mdast-zone@6'
In browsers with
esm.sh
esmsh:<script type="module">
import {zone} from 'https://esm.sh/mdast-zone@6?bundle'
</script>
Use
Say we have the following file,example.md
:<!--foo start-->
Foo
<!--foo end-->
…and a module
example.js
:import {zone} from 'mdast-zone'
import {remark} from 'remark'
import {read} from 'to-vfile'
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) {
zone(tree, 'foo', function (start, nodes, end) {
return [
start,
{type: 'paragraph', children: [{type: 'text', value: 'Bar.'}]},
end
]
})
}
}
…now running
node example.js
yields:<!--foo start-->
Bar.
<!--foo end-->
API
This package exports the identifierzone
api-zone.
There is no default export.zone(tree, name, handler)
Search tree
for a start and end comments matching name
and change their
“section” with handler
.Parameters
— tree to changename
(string
)
handler
(Handler
api-handler)
Returns
Nothing (undefined
).Handler
Callback called when a section is found (TypeScript type).Parameters
— start of sectionnodes
(Array<Node>
node)
start
and end
— end of section
— extra infoReturns
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 sectionstart
(number
)
start
in parent
end
(number
)
end
in parent
Types
This package is fully typed with TypeScript. It exports the additional typesHandler
api-handler and
Info
api-info.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-zone@^6
,
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 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: '<script>alert(1)</script>'}, end]
}
Yields:
<!--foo start-->
<script>alert(1)</script>
<!--foo end-->
Either do not use user input or use
hast-util-santize
hast-util-sanitize.Related
— similar but uses headings to mark sectionsContribute
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, organization, or community you agree to abide by its terms.