mdast utility to transform to hast.
Note: You probably want to use
remark-rehype
.
This package is ESM only:
Node 12+ is needed to use it and it must be import
ed instead of require
d.
npm:
npm install mdast-util-to-hast
Say we have the following example.md
:
## Hello **World**!
…and next to it, example.js
:
import fs from 'fs'
import fromMarkdown from 'mdast-util-from-markdown'
import {toHast} from 'mdast-util-to-hast'
import toHtml from 'hast-util-to-html'
var mdast = fromMarkdown(fs.readFileSync('example.md'))
var hast = toHast(mdast)
var html = toHtml(hast)
console.log(html)
Which when running with node example
yields:
<h2>Hello <strong>World</strong>!</h2>
This package exports the following identifiers: toHast
.
There is no default export.
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.
Object mapping mdast nodes to functions handling them.
Take a look at lib/handlers/
for examples.
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.
Handler for unknown nodes (that aren’t in handlers
or passThrough
).
Default behavior:
- Unknown nodes with
children
are transformed todiv
elements - Unknown nodes with
value
are transformed totext
nodes
yaml
andtoml
nodes are ignored (created byremark-frontmatter
)html
nodes are ignored ifallowDangerousHtml
isfalse
position
s are properly patchednode.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- GFM (and this project) uses the obsolete
align
attribute ontd
andth
elements; combine this utility with@mapbox/hast-util-table-cell-style
to usestyle
instead
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.