mdast-util-to-hast

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 install mdast-util-to-hast

Use

Say we have the following example.md:

## Hello **World**!

…and next to it, example.js:

import fs from 'node:fs'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toHast} from 'mdast-util-to-hast'
import {toHtml} from 'hast-util-to-html'

const mdast = fromMarkdown(fs.readFileSync('example.md'))
const hast = toHast(mdast)
const 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, defaultHandlers, all, one 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.clobberPrefix`

Prefix to use before the id attribute on footnotes to prevent it from clobbering (string, default: 'user-content-'). DOM clobbering is this:

<p id=x></p>
<script>alert(x)</script>

Elements by their ID are made available in browsers on the window object. Using a prefix this that from being a problem.

`options.footnoteLabel`

Label to use for the footnotes section (string, default: 'Footnotes'). Affects screen reader users. Change it if you’re authoring in a different language.

`options.footnoteBackLabel`

Label to use from backreferences back to their footnote call (string, default: 'Back to content'). Affects screen reader users. Change it if you’re authoring in a different language.

`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 children are transformed to div elements
Unknown nodes with value are transformed to text nodes

Returns

HastNode.

Notes

yaml and toml nodes are ignored (created by remark-frontmatter)
html nodes are ignored if allowDangerousHtml is false
positions are properly patched
node.data.hName configures the hast element’s tag-name
node.data.hProperties is mixed into the hast element’s properties
node.data.hChildren configures the hast element’s children
GFM (and this project) uses the obsolete align attribute on td and th elements; combine this utility with @mapbox/hast-util-table-cell-style to use style instead

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: ';'}
    ]
  }]
}

`defaultHandlers`

Object mapping mdast node types to functions that can handle them. See lib/handlers/index.js.

`all(h, parent)`

Helper function for writing custom handlers passed to options.handlers. Pass it h and a parent node (mdast) and it will turn the node’s children into an array of transformed nodes (hast).

`one(h, node, parent)`

Helper function for writing custom handlers passed to options.handlers. Pass it h, a node, and its parent (mdast) and it will turn node into hast content.

Recommended CSS

The following CSS is needed to make footnotes look a bit like GitHub. For the complete actual CSS that GitHub uses see sindresorhus/github-markdown-css.

/* Style the footnotes section. */
.footnotes {
  font-size: smaller;
  color: #8b949e;
  border-top: 1px solid #30363d;
}

/* Hide the section label for visual users. */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  word-wrap: normal;
  border: 0;
}

/* Place `[` and `]` around footnote calls. */
[data-footnote-ref]::before {
  content: '[';
}

[data-footnote-ref]::after {
  content: ']';
}

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.

mdast-util-to-nlcst — transform mdast to nlcst
hast-util-to-mdast — transform hast to mdast
hast-util-to-xast — transform hast to xast
hast-util-sanitize — sanitize hast nodes
remark-rehype — rehype support for remark
rehype-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.

mdast-util-to-hast

Install

Use

API

`toHast(node[, options])`

Options

`options.allowDangerousHtml`

`options.clobberPrefix`

`options.footnoteLabel`

`options.footnoteBackLabel`

`options.handlers`

`options.passThrough`

`options.unknownHandler`

Returns

Notes

Examples

`hName`

`hProperties`

`hChildren`

`defaultHandlers`

`all(h, parent)`

`one(h, node, parent)`

Recommended CSS

Security

Related

Contribute

License

Current Tags

10 Versions