unified

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

Package: mdast-util-to-hast@9.1.0

  1. Dependencies: 11·Dependents: 61
  2. mdast utility to transform to hast
  1. util 107
  2. utility 105
  3. html 101
  4. unist 95
  5. markdown 88
  6. mdast 72
  7. hast 57
  8. hast-util 40
  9. mdast-util 15

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

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.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:

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