unified

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

Package: hast-util-to-xast@2.0.1

  1. hast utility to transform to xast
  1. 67%
  3. MIT
  4. 4
  1. 28k
  1. util 130
  2. utility 126
  3. html 120
  4. unist 116
  5. hast 75
  6. hast-util 46
  7. xml 9
  8. xast 7
  9. xast-util 6
  10. dsl 4

hast-util-to-xast

Build Coverage Downloads Size

hast (HTML) utility to transform to xast (XML).

Contents

What is this?

This package is a utility that takes a hast (HTML) syntax tree as input and turns it into a xast (XML) syntax tree. This package also supports embedded MDX nodes.

When should I use this?

This project is useful when you want to deal with ASTs, and for some reason, have to deal with XML. One example of this is for EPUB (digital books).

There is no inverse of this utility, because not all XML is HTML.

A similar package, hast-util-to-estree, can turn hast into estree (JavaScript) as JSX, which has some similarities to XML.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install hast-util-to-xast

In Deno with esm.sh:

import {toXast} from 'https://esm.sh/hast-util-to-xast@3'

In browsers with esm.sh:

<script type="module">
  import {toXast} from 'https://esm.sh/hast-util-to-xast@3?bundle'
</script>

Use

Say our document example.html contains:

<!doctypehtml>
<title>Hello, World!</title>
<h1>👋, 🌍</h1>

…and our module example.js looks as follows:

import fs from 'node:fs/promises'
import {fromHtml} from 'hast-util-from-html'
import {toXast} from 'hast-util-to-xast'
import {toXml} from 'xast-util-to-xml'

// Get the HTML syntax tree:
const hast = fromHtml(await fs.readFile('example.html'))

// Turn hast to xast:
const xast = toXast(hast)

// Serialize xast:
console.log(toXml(xast))

…now running node example.js yields:

<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"><head><title>Hello, World!</title>
</head><body><h1>👋, 🌍</h1>
</body></html>

API

This package exports the identifier toXast. There is no default export.

toXast(tree[, options])

Turn a hast tree into a xast tree.

Parameters
Returns

xast tree (XastNode).

Options

Configuration (TypeScript type).

Fields
space

Which space the document is in (Space, default: 'html').

When an <svg> element is found in the HTML space, this package already automatically switches to and from the SVG space when entering and exiting it.

You can also switch explicitly with xmlns properties in hast, but note that only HTML and SVG are supported.

Space

Namespace (TypeScript type).

Type
type Space = 'html' | 'svg'

Types

This package is fully typed with TypeScript. It exports the additional types Options and Space.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, hast-util-to-xast@3, compatible with Node.js 16.

Security

Both HTML and XML can be dangerous languages: don’t trust user-provided data. Use hast-util-santize to make the hast tree safe before using this utility.

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