hast utility to transform from a `parse5` AST
npm install hast-util-from-parse5[![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]
[hast][github-hast] utility to transform from the
[parse5][github-parse5] AST.
* What is this?
* When should I use this?
* Install
* Use
* API
* [fromParse5(tree[, options])](#fromparse5tree-options)
* Options
* Space
* Types
* Compatibility
* Security
* Related
* Contribute
* License
This package is a utility that can turn a parse5 tree into a hast tree.
You can use this package when using parse5 as an HTML parser and wanting to
work with hast.
The utility [hast-util-to-parse5][github-hast-util-to-parse5] does the
inverse of this utility.
It generates parse5s AST again.
The utility [hast-util-from-html][github-hast-util-from-html] wraps this
utility and parse5 to both parse HTML and generate hast from it.
This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npmjs-install]:
``sh`
npm install hast-util-from-parse5
In Deno with [esm.sh][esmsh]:
`js`
import {fromParse5} from "https://esm.sh/hast-util-from-parse5@8"
In browsers with [esm.sh][esmsh]:
`html`
Say our document example.html contains:
`html`World!
…and our module example.js looks as follows:
`js
import {fromParse5} from 'hast-util-from-parse5'
import {parse} from 'parse5'
import {read} from 'to-vfile'
import {inspect} from 'unist-util-inspect'
const file = await read('example.html')
const p5ast = parse(String(file), {sourceCodeLocationInfo: true})
const hast = fromParse5(p5ast, {file})
console.log(inspect(hast))
`
…now running node example.js yields:
`text`
root[2] (1:1-2:1, 0-70)
│ data: {"quirksMode":false}
├─0 doctype (1:1-1:16, 0-15)
└─1 element[2]
│ properties: {}
├─0 element[1]
│ │ properties: {}
│ └─0 element
│ │ properties: {}
│ └─0 text "Hello!" (1:23-1:29, 22-28)
└─1 element
│ properties: {}
└─0 element[3] (1:37-2:1, 36-70)
│ properties: {"id":"world"}
├─0 text "World!" (1:52-1:58, 51-57)
├─1 comment "after" (1:58-1:70, 57-69)
└─2 text "\n" (1:70-2:1, 69-70)
This package exports the identifier [fromParse5][api-from-parse5].
There is no default export.
Transform a parse5 AST to hast.
###### Parameters
* treeParse5Node
([][github-parse5-node])parse5
— tree to transformoptions
* Options
([][api-options], optional)
— configuration
###### Returns
hast tree ([HastNode][github-hast-nodes]).
Configuration (TypeScript type).
##### Fields
###### file
File used to add positional info to nodes
([VFile][github-vfile], optional).
If given,
the file should represent the original HTML source.
###### space
Which space the document is in
([Space][api-space], default: 'html').
When an
###### verbose
Whether to add extra positional info about starting tags,
closing tags,
and attributes to elements
(boolean, default: false).
> 👉 Note:
> only used when file is given.
For the following HTML:
`html`
The verbose info would looks as follows:
`js`
{
type: 'element',
tagName: 'img',
properties: {src: 'http://example.com/fav.ico', alt: 'foo', title: 'bar'},
children: [],
data: {
position: {
opening: {
start: {line: 1, column: 1, offset: 0},
end: {line: 1, column: 61, offset: 60}
},
closing: null,
properties: {
src: {
start: {line: 1, column: 6, offset: 5},
end: {line: 1, column: 38, offset: 37}
},
alt: {
start: {line: 1, column: 39, offset: 38},
end: {line: 1, column: 48, offset: 47}
},
title: {
start: {line: 1, column: 49, offset: 48},
end: {line: 1, column: 60, offset: 59}
}
}
}
},
position: {
start: {line: 1, column: 1, offset: 0},
end: {line: 1, column: 61, offset: 60}
}
}
Namespace (TypeScript type).
###### Type
`ts`
type Space = 'html' | 'svg'
This package is fully typed with [TypeScript][].
It exports the additional types [Options][api-options] andSpace
[][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-from-parse5@8,
compatible with Node.js 16.
Use of hast-util-from-parse5 can open you up to a
[cross-site scripting (XSS)][wikipedia-xss] attack if Parse5’s AST is unsafe.
* [hast-util-to-parse5][github-hast-util-to-parse5]hast-util-to-nlcst
— transform hast to Parse5’s AST
* hast-util-to-mdast
— transform hast to nlcst
* hast-util-to-xast
— transform hast to mdast
* mdast-util-to-hast
— transform hast to xast
* mdast-util-to-nlcst
— transform mdast to hast
*
— transform mdast to nlcst
See [contributing.md][health-contributing]syntax-tree/.github
in
[][health]support.md`][health-support] for ways to get help.
for ways to get started.
See [
This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.
[MIT][file-license] © [Titus Wormer][wooorm]
[api-from-parse5]: #fromparse5tree-options
[api-options]: #options
[api-space]: #space-1
[badge-build-image]: https://github.com/syntax-tree/hast-util-from-parse5/workflows/main/badge.svg
[badge-build-url]: https://github.com/syntax-tree/hast-util-from-parse5/actions
[badge-coverage-image]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-from-parse5.svg
[badge-coverage-url]: https://codecov.io/github/syntax-tree/hast-util-from-parse5
[badge-downloads-image]: https://img.shields.io/npm/dm/hast-util-from-parse5.svg
[badge-downloads-url]: https://www.npmjs.com/package/hast-util-from-parse5
[badge-size-image]: https://img.shields.io/bundlejs/size/hast-util-from-parse5
[badge-size-url]: https://bundlejs.com/?q=hast-util-from-parse5
[esmsh]: https://esm.sh
[file-license]: license
[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[github-hast]: https://github.com/syntax-tree/hast
[github-hast-nodes]: https://github.com/syntax-tree/hast#nodes
[github-hast-util-from-html]: https://github.com/syntax-tree/hast-util-from-html
[github-hast-util-to-parse5]: https://github.com/syntax-tree/hast-util-to-parse5
[github-parse5]: https://github.com/inikulin/parse5
[github-parse5-node]: https://github.com/inikulin/parse5/blob/master/packages/parse5/lib/tree-adapters/default.ts
[github-vfile]: https://github.com/vfile/vfile
[health]: https://github.com/syntax-tree/.github
[health-coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
[health-contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
[health-support]: https://github.com/syntax-tree/.github/blob/main/support.md
[npmjs-install]: https://docs.npmjs.com/cli/install
[typescript]: https://www.typescriptlang.org
[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[wooorm]: https://wooorm.com