unified

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

Package:hast-util-to-mdast@6.0.0

  1. Dependencies:11·Dependents:5
  2. Transform hast to mdast
  1. remark 166
  2. markdown 82
  3. hast 78
  4. rehype 76
  5. mdast 68
  6. html 56

hast-util-to-mdast

Build Coverage Downloads Size Sponsors Backers Chat

hast utility to transform to mdast.

Note: You probably want to use rehype-remark.

Install

npm:

npm install hast-util-to-mdast

Usage

Say we have the following example.html:

<h2>Hello <strong>world!</strong></h2>

…and next to it, example.js:

var unified = require('unified')
var parse = require('rehype-parse')
var stringify = require('remark-stringify')
var vfile = require('to-vfile')
var toMdast = require('hast-util-to-mdast')

var file = vfile.readSync('example.html')

var hast = unified()
  .use(parse)
  .parse(file)

var mdast = toMdast(hast)

var doc = unified()
  .use(stringify)
  .stringify(mdast)

console.log(doc)

Now, running node example.js yields:

## Hello **world!**

API

toMdast(tree[, options])

Transform the given hast tree to mdast.

Options
options.handlers

Object mapping tag names or types to functions handling those elements or nodes. See handlers/ for examples.

options.document

Whether the given tree is a complete document. Applies if the given tree is a root. First its children are transformed to mdast. By default, if one or more of the new mdast children are phrasing nodes, and one or more are not, the phrasing nodes are wrapped in paragraphs. If document: true, all mdast phrasing children are wrapped in paragraphs.

options.newlines

Whether to collapse to a line feed (\n) instead of a single space (default) if a streak of white-space in a text node contains a newline.

Returns

MdastNode.

Notes
Implied paragraphs

The algorithm supports implicit and explicit paragraphs (see HTML Standard, A. van Kesteren; et al. WHATWG § 3.2.5.4 Paragraphs), such as:

<article>
  An implicit paragraph.
  <h1>An explicit paragraph.</h1>
</article>

Yields:

An implicit paragraph.

# An explicit paragraph.
Ignoring nodes

Some nodes are ignored and their content will not be present in the mdast tree. To ignore nodes, configure a handler for their tag name or type that returns nothing. For example, to ignore em elements, pass handlers: {'em': function () {}}:

<p><strong>Importance</strong> and <em>emphasis</em>.</p>

Yields:

**Importance** and .

To ignore a specific element from the HTML source, set data-mdast to ignore:

<p><strong>Importance</strong> and <em data-mdast="ignore">emphasis</em>.</p>

Yields:

**Importance** and .
HTML in Markdown

We try our best to map any HTML (hast) to Markdown (mdast) and keep it readable. Readability is one of Markdown’s greatest features: it’s terser than HTML, such as allowing # Alpha instead of <h1>Alpha</h1>.

Another awesome feature of Markdown is that you can author HTML inside it. As we focus on readability we don’t do that, but you can by passing a handler.

Say we for example have this HTML, and want to embed the SVG inside Markdown as well:

<p>
  Some text with
  <svg viewBox="0 0 1 1" width="1" height="1"><rect fill="black" x="0" y="0" width="1" height="1" /></svg>
  a graphic… Wait is that a dead pixel?
</p>

This can be achieved with example.js like so:

var unified = require('unified')
var parse = require('rehype-parse')
var stringify = require('remark-stringify')
var vfile = require('to-vfile')
var toHtml = require('hast-util-to-html')
var toMdast = require('hast-util-to-mdast')

var file = vfile.readSync('example.html')

var hast = unified()
  .use(parse)
  .parse(file)

var mdast = toMdast(hast, {handlers: {svg: svg}})

var doc = unified()
  .use(stringify)
  .stringify(mdast)

console.log(doc)

function svg(h, node) {
  return h.augment(node, {type: 'html', value: toHtml(node, {space: 'svg'})})
}

Yields:

Some text with <svg viewBox="0 0 1 1" width="1" height="1"><rect fill="black" x="0" y="0" width="1" height="1"></rect></svg> a graphic… Wait is that a dead pixel?

Security

Use of hast-util-to-mdast can open you up to a cross-site scripting (XSS) attack if the hast tree is unsafe. Use hast-util-santize 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, organisation, or community you agree to abide by its terms.

License

MIT © Titus Wormer