hast-util-to-xast
Version:
hast utility to transform to xast
266 lines (177 loc) • 6.46 kB
Markdown
[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
[][github-hast] (HTML) utility to transform to [xast][github-xast] (XML).
* [What is this?](
* [When should I use this?](
* [Install](
* [Use](
* [API](
* [`toXast(tree[, options])`](
* [`Options`](
* [`Space`](
* [Types](
* [Compatibility](
* [Security](
* [Related](
* [Contribute](
* [License](
This package is a utility that takes a
[][github-hast] (HTML)
syntax tree as input and turns it into a
[][github-xast] (XML)
syntax tree.
This package also supports embedded MDX nodes.
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`][github-hast-util-to-estree],
can turn hast into estree (JavaScript) as JSX,
which has some similarities to XML.
## Install
This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npmjs-install]:
```sh
npm install hast-util-to-xast
```
In Deno with [`esm.sh`][esmsh]:
```js
import {toXast} from 'https://esm.sh/hast-util-to-xast@3'
```
In browsers with [`esm.sh`][esmsh]:
```html
<script type="module">
import {toXast} from 'https://esm.sh/hast-util-to-xast@3?bundle'
</script>
```
Say our document `example.html` contains:
```html
<!doctypehtml>
<title>Hello, World!</title>
<h1>👋, 🌍</h1>
```
…and our module `example.js` looks as follows:
```js
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:
```xml
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"><head><title>Hello, World!</title>
</head><body><h1>👋, 🌍</h1>
</body></html>
```
This package exports the identifier [`toXast`][api-to-xast].
There is no default export.
Turn a [hast][github-hast] tree into a [xast][github-xast] tree.
* `tree`
([`HastNode`][github-hast-nodes])
— hast tree to transform
* `options`
([`Options`][api-options], optional)
— configuration
xast tree ([`XastNode`][github-xast-nodes]).
### `Options`
Configuration (TypeScript type).
##### Fields
###### `space`
Which space the document is in
([`Space`][api-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
```ts
type Space = 'html' | 'svg'
```
This package is fully typed with [TypeScript][].
It exports the additional types [`Options`][api-options] and
[`Space`][api-space].
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.
Both HTML and XML can be dangerous languages:
don’t trust user-provided data.
Use [`hast-util-santize`][github-hast-util-sanitize]
to make the hast tree safe before using this utility.
* [`hastscript`](https://github.com/syntax-tree/hastscript)
— create [hast][github-hast] (HTML or SVG) trees
* [`xastscript`](https://github.com/syntax-tree/xastscript)
— create [xast][github-xast] (XML) trees
* [`xast-util-to-xml`](https://github.com/syntax-tree/xast-util-to-xml)
— serialize as XML
See [`contributing.md`][health-contributing]
in
[`syntax-tree/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.
This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.
[][file-license] © [Titus Wormer][wooorm]
<!-- Definitions -->
[]:
[]:
[]:
[]: https://github.com/syntax-tree/hast-util-to-xast/workflows/main/badge.svg
[]: https://github.com/syntax-tree/hast-util-to-xast/actions
[]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-to-xast.svg
[]: https://codecov.io/github/syntax-tree/hast-util-to-xast
[]: https://img.shields.io/npm/dm/hast-util-to-xast.svg
[]: https://www.npmjs.com/package/hast-util-to-xast
[]: https://img.shields.io/bundlejs/size/hast-util-to-xast
[]: https://bundlejs.com/?q=hast-util-to-xast
[]: https://esm.sh
[]: license
[]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[]: https://github.com/syntax-tree/hast
[]: https://github.com/syntax-tree/hast#nodes
[]: https://github.com/syntax-tree/hast-util-sanitize
[]: https://github.com/syntax-tree/hast-util-to-estree
[]: https://github.com/syntax-tree/xast
[]: https://github.com/syntax-tree/xast#nodes
[]: https://github.com/syntax-tree/.github
[]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
[]: https://github.com/syntax-tree/.github/blob/main/contributing.md
[]: https://github.com/syntax-tree/.github/blob/main/support.md
[]: https://docs.npmjs.com/cli/install
[]: https://www.typescriptlang.org
[]: https://wooorm.com