JarCastingmdast-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
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.handlers
Object mapping mdast nodes to functions handling them. Take a look at lib/handlers/ for examples.
options.passThrough
List of custom mdast node types to pass through (keep) in hast (Array.<string>, default: []). If the passed through nodes have children, those children are expected to be mdast and will be handled.
options.unknownHandler
Handler for unknown nodes (that aren’t in handlers or passThrough).
Default behavior:
- Unknown nodes with
childrenare transformed todivelements - Unknown nodes with
valueare transformed totextnodes
Returns
Notes
yamlandtomlnodes are ignored (created byremark-frontmatter)htmlnodes are ignored ifallowDangerousHtmlisfalsepositions are properly patchednode.data.hNameconfigures the hast element’s tag-namenode.data.hPropertiesis mixed into the hast element’s propertiesnode.data.hChildrenconfigures the hast element’s children- GFM (and this project) uses the obsolete
alignattribute ontdandthelements; combine this utility with@mapbox/hast-util-table-cell-styleto usestyleinstead
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
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
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.
