mdast utility to transform to hast.
Note: You probably want to use
remark-rehype
.
npm:
npm install mdast-util-to-hast
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)
Transform the given mdast tree to a hast tree.
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.
Set to true
(default: false
) to prefer the first when duplicate definitions
are found.
The default behaviour is to prefer the last duplicate definition.
Object mapping mdast nodes to functions handling them.
Take a look at lib/handlers/
for examples.
yaml
andtoml
nodes are ignored (created byremark-frontmatter
)html
nodes are ignored ifallowDangerousHTML
isfalse
position
s are properly patched- Unknown nodes with
children
are transformed todiv
elements - Unknown nodes with
value
are transformed totext
nodes node.data.hName
configures the hast element’s tag-namenode.data.hProperties
is mixed into the hast element’s propertiesnode.data.hChildren
configures the hast element’s children
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'}]
}
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: []
}
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: ';'}
]
}]
}
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.
mdast-util-to-nlcst
— transform mdast to nlcsthast-util-to-mdast
— transform hast to mdasthast-util-to-xast
— transform hast to xasthast-util-sanitize
— sanitize hast nodesremark-rehype
— rehype support for remarkrehype-remark
— remark support for rehype
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.