unified

Project: syntax-tree/mdast-util-to-hast

Package: mdast-util-to-hast@11.0.0

  1. Dependencies: 0·Dependents: 74
  2. mdast utility to transform to hast
  1. util 129
  2. markdown 127
  3. utility 125
  4. unist 119
  5. html 111
  6. mdast 89
  7. hast 60
  8. hast-util 40
  9. mdast-util 29

mdast-util-to-hast

Build Coverage Downloads Size Sponsors Backers Chat

mdast utility to transform to hast.

Note: You probably want to use remark-rehype.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install mdast-util-to-hast

Use

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>

API

This package exports the following identifiers: toHast. There is no default export.

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:

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>
&#x3C;script>alert(3)&#x3C;/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.

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