mdast-util-to-hast
mdast utility to transform to hast.
Note: You probably want to use remark-rehype
.
Install
npm:
npm install mdast-util-to-hast
npm with TypeScript support:
npm install mdast-util-to-hast @types/mdast
Use
Say we have the following example.md
:
## Hello **World**!
…and next to it, example.js
:
var inspect = require('unist-util-inspect')
var unified = require('unified')
var parse = require('remark-parse')
var vfile = require('to-vfile')
var toHast = require('mdast-util-to-hast')
var tree = unified()
.use(parse)
.parse(vfile.readSync('example.md'))
console.log(inspect(toHast(tree)))
Which when running with node example
yields:
root[1] (1:1-2:1, 0-20)
└─ element[3] (1:1-1:20, 0-19) [tagName="h2"]
├─ text: "Hello " (1:4-1:10, 3-9)
├─ element[1] (1:10-1:19, 9-18) [tagName="strong"]
│ └─ text: "World" (1:12-1:17, 11-16)
└─ text: "!" (1:19-1:20, 18-19)
API
toHast(node[, options])
Transform the given mdast tree to a hast tree.
Options
options.allowDangerousHtml
Whether to allow html
nodes and inject them as raw HTML
(boolean
, default: false
).
Only do this when using hast-util-to-html
(rehype-stringify
) or hast-util-raw
(rehype-raw
) later: raw
nodes are not a standard part of
hast.
options.commonmark
Set to true
(default: false
) to prefer the first when duplicate definitions
are found.
The default behavior is to prefer the last duplicate definition.
options.handlers
Object mapping mdast nodes to functions handling them.
Take a look at lib/handlers/
for examples.
options.unknownHandler
Handler for all unknown nodes.
Default behavior:
- Unknown nodes with
children
are transformed to div
elements - Unknown nodes with
value
are transformed to text
nodes
Returns
HastNode
.
Notes
Examples
hName
node.data.hName
sets the tag-name of an element.
The following mdast:
{
type: 'strong',
data: {hName: 'b'},
children: [{type: 'text', value: 'Alpha'}]
}
Yields, in hast:
{
type: 'element',
tagName: 'b',
properties: {},
children: [{type: 'text', value: 'Alpha'}]
}
hProperties
node.data.hProperties
in sets the properties of an element.
The following mdast:
{
type: 'image',
src: 'circle.svg',
alt: 'Big red circle on a black background',
title: null
data: {hProperties: {className: ['responsive']}}
}
Yields, in hast:
{
type: 'element',
tagName: 'img',
properties: {
src: 'circle.svg',
alt: 'Big red circle on a black background',
className: ['responsive']
},
children: []
}
hChildren
node.data.hChildren
sets the children of an element.
The following mdast:
{
type: 'code',
lang: 'js',
data: {
hChildren: [
{
type: 'element',
tagName: 'span',
properties: {className: ['hljs-meta']},
children: [{type: 'text', value: '"use strict"'}]
},
{type: 'text', value: ';'}
]
},
value: '"use strict";'
}
Yields, in hast (note: the pre
and language-js
class are normal
mdast-util-to-hast
functionality):
{
type: 'element',
tagName: 'pre',
properties: {},
children: [{
type: 'element',
tagName: 'code',
properties: {className: ['language-js']},
children: [
{
type: 'element',
tagName: 'span',
properties: {className: ['hljs-meta']},
children: [{type: 'text', value: '"use strict"'}]
},
{type: 'text', value: ';'}
]
}]
}
Security
Use of mdast-util-to-hast
can open you up to a
cross-site scripting (XSS) attack.
Embedded hast properties (hName
, hProperties
, hChildren
), custom handlers,
and the allowDangerousHtml
option all provide openings.
The following example shows how a script is injected where a benign code block
is expected with embedded hast properties:
var code = {type: 'code', value: 'alert(1)'}
code.data = {hName: 'script'}
Yields:
<script>alert(1)</script>
The following example shows how an image is changed to fail loading and
therefore run code in a browser.
var image = {type: 'image', url: 'existing.png'}
image.data = {hProperties: {src: 'missing', onError: 'alert(2)'}}
Yields:
<img src="missing" onerror="alert(2)">
The following example shows the default handling of embedded HTML:
# Hello
<script>alert(3)</script>
Yields:
<h1>Hello</h1>
Passing allowDangerousHtml: true
to mdast-util-to-hast
is typically still
not enough to run unsafe code:
<h1>Hello</h1>
<script>alert(3)</script>
If allowDangerousHtml: true
is also given to hast-util-to-html
(or
rehype-stringify
), the unsafe code runs:
<h1>Hello</h1>
<script>alert(3)</script>
Use hast-util-sanitize
to make the hast tree safe.
Related
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