Skip to content

Commit ace5f7a

Browse files
wooormwooorm
committed
Add improved docs
1 parent cd0abcd commit ace5f7a

File tree

1 file changed

+124
-65
lines changed

1 file changed

+124
-65
lines changed

Diff for: ‎readme.md

+124-65
Original file line numberDiff line numberDiff line change
@@ -8,106 +8,155 @@
88
[![Backers][backers-badge]][collective]
99
[![Chat][chat-badge]][chat]
1010

11-
[**hast**][hast] utility to transform from a DOM tree.
11+
[hast][] utility to transform from a [DOM][] tree.
1212

13-
## Install
13+
## Contents
14+
15+
* [What is this?](#what-is-this)
16+
* [When should I use this?](#when-should-i-use-this)
17+
* [Install](#install)
18+
* [Use](#use)
19+
* [API](#api)
20+
* [`fromDom(node)`](#fromdomnode)
21+
* [Types](#types)
22+
* [Compatibility](#compatibility)
23+
* [Security](#security)
24+
* [Contribute](#contribute)
25+
* [Related](#related)
26+
* [License](#license)
27+
28+
## What is this?
29+
30+
This package is a utility that takes a DOM tree (from the actual DOM or from
31+
things like [`jsdom`][jsdom]) as input and turns it into a [hast][] (HTML)
32+
syntax tree.
33+
34+
## When should I use this?
35+
36+
You can use this project when you want to use hast in browsers.
37+
This package is very small, but it does so by:
1438

15-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
16-
Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
39+
* …not providing positional information
40+
* …potentially yielding varying results in different (especially older)
41+
browsers
1742

18-
[npm][]:
43+
The hast utility [`hast-util-to-dom`][hast-util-to-dom] does the inverse of this
44+
utility.
45+
It turns hast into a DOM tree.
46+
47+
The rehype plugin [`rehype-dom-parse`][rehype-dom-parse] wraps this utility to
48+
parse HTML with DOM APIs.
49+
50+
## Install
51+
52+
This package is [ESM only][esm].
53+
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
1954

2055
```sh
2156
npm install hast-util-from-dom
2257
```
2358

24-
## Use
59+
In Deno with [`esm.sh`][esmsh]:
2560

26-
This utility is similar to [`hast-util-from-parse5`][hast-util-from-parse5], but
27-
is intended for browser use and therefore relies on the native DOM API instead
28-
of an external parsing library.
61+
```js
62+
import {fromDom} from 'https://esm.sh/hast-util-from-dom@4'
63+
```
2964

30-
Say we have the following file, `example.html`:
65+
In browsers with [`esm.sh`][esmsh]:
3166

3267
```html
33-
<!doctype html><title>Hello!</title><h1 id="world">World!<!--after--><script src="example.js" charset="UTF-8"></script>
68+
<script type="module">
69+
import {fromDom} from 'https://esm.sh/hast-util-from-dom@4?bundle'
70+
</script>
3471
```
3572

36-
Suppose `example.js` is a bundled version of something like this:
37-
38-
```js
39-
import {inspect} from 'unist-util-inspect'
40-
import {fromDom} from 'hast-util-from-dom'
73+
## Use
4174

42-
const hast = fromDom(document)
75+
Say our page `example.html` looks as follows:
4376

44-
console.log(inspect.noColor(hast))
77+
```html
78+
<!doctype html>
79+
<title>Example</title>
80+
<body>
81+
<main>
82+
<h1>Hi</h1>
83+
<p><em>Hello</em>, world!</p>
84+
</main>
85+
<script type="module">
86+
import {fromDom} from 'https://esm.sh/hast-util-from-dom@4?bundle'
87+
88+
const hast = fromDom(document.querySelector('main'))
89+
90+
console.log(hast)
91+
</script>
4592
```
4693

47-
Viewing `example.html` in a browser should yield the following in the console:
48-
49-
```text
50-
root[2]
51-
├─ doctype [name="html"]
52-
└─ element[2] [tagName="html"]
53-
├─ element[1] [tagName="head"]
54-
│ └─ element[1] [tagName="title"]
55-
│ └─ text: "Hello!"
56-
└─ element[1] [tagName="body"]
57-
└─ element[3] [tagName="h1"][properties={"id":"world"}]
58-
├─ text: "World!"
59-
├─ comment: "after"
60-
└─ element[0] [tagName="script"][properties={"src":"example.js","charSet":"UTF-8"}]
94+
Now running `open example.html` prints the following to the console:
95+
96+
```js
97+
{type: "element", tagName: "main", properties: {}, children: Array}
6198
```
6299

63100
## API
64101

65-
This package exports the following identifiers: `fromDom`.
102+
This package exports the identifier `fromDom`.
66103
There is no default export.
67104

68105
### `fromDom(node)`
69106

70-
Transform a DOM tree to a [**hast**][hast] [*tree*][tree].
107+
Turn a DOM tree into a hast tree.
71108

72-
This works in a similar way to the [`parse5`][hast-util-from-parse5] version
73-
except that it works directly from the DOM rather than a string of HTML.
74-
Consequently, it does not maintain [positional info][positional-information].
109+
##### options
75110

76-
##### `options`
111+
Configuration (optional).
77112

78113
###### `options.afterTransform`
79114

80-
Function called after a DOM node is transformed into a hast node (`Function?`).
81-
Given the DOM node that was handled as the first parameter and the
82-
corresponding hast node as the second parameter.
115+
Called when a DOM node was transformed into a hast node
116+
(`(Node, HastNode) => void?`).
83117

84-
## Security
118+
##### Returns
85119

86-
Use of `hast-util-from-dom` can open you up to a
87-
[cross-site scripting (XSS)][xss] attack if the DOM is unsafe.
88-
Use [`hast-util-santize`][sanitize] to make the hast tree safe.
120+
[`HastNode`][hast-node].
89121

90-
## Related
122+
## Types
91123

92-
* [`hast-util-from-parse5`][hast-util-from-parse5]
93-
— Create a hast tree from Parse5’s AST
94-
* [`hast-util-sanitize`](https://github.com/syntax-tree/hast-util-sanitize)
95-
— Sanitize hast nodes
96-
* [`hast-util-to-html`](https://github.com/syntax-tree/hast-util-to-html)
97-
— Create an HTML string
98-
* [`hast-util-to-dom`](https://github.com/syntax-tree/hast-util-to-dom)
99-
— Create a DOM tree from a hast tree
124+
This package is fully typed with [TypeScript][].
125+
It exports the additional type `Options`.
126+
127+
## Compatibility
128+
129+
Projects maintained by the unified collective are compatible with all maintained
130+
versions of Node.js.
131+
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
132+
Our projects sometimes work with older versions, but this is not guaranteed.
133+
134+
## Security
135+
136+
Use of `hast-util-from-dom` itself is safe but see other utilities for more
137+
information on potential security problems.
100138

101139
## Contribute
102140

103-
See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
104-
started.
141+
See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
142+
ways to get started.
105143
See [`support.md`][support] for ways to get help.
106144

107145
This project has a [code of conduct][coc].
108-
By interacting with this repository, organization, or community you agree to
146+
By interacting with this repository, organisation, or community you agree to
109147
abide by its terms.
110148

149+
## Related
150+
151+
* [`hast-util-from-parse5`][hast-util-from-parse5]
152+
— create hast from Parse5’s AST
153+
* [`hast-util-sanitize`](https://github.com/syntax-tree/hast-util-sanitize)
154+
— sanitize hast nodes
155+
* [`hast-util-to-html`](https://github.com/syntax-tree/hast-util-to-html)
156+
— serialize hast as HTML
157+
* [`hast-util-to-dom`](https://github.com/syntax-tree/hast-util-to-dom)
158+
— create DOM trees from hast
159+
111160
## License
112161

113162
[ISC][license] © [Keith McKnight][author]
@@ -142,24 +191,34 @@ abide by its terms.
142191

143192
[npm]: https://docs.npmjs.com/cli/install
144193

194+
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
195+
196+
[esmsh]: https://esm.sh
197+
198+
[typescript]: https://www.typescriptlang.org
199+
145200
[license]: license
146201

147202
[author]: https://keith.mcknig.ht
148203

149-
[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
150-
151-
[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
204+
[health]: https://github.com/syntax-tree/.github
152205

153-
[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
206+
[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
154207

155-
[tree]: https://github.com/syntax-tree/unist#tree
208+
[support]: https://github.com/syntax-tree/.github/blob/main/support.md
156209

157-
[positional-information]: https://github.com/syntax-tree/unist#positional-information
210+
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
158211

159212
[hast]: https://github.com/syntax-tree/hast
160213

214+
[hast-node]: https://github.com/syntax-tree/hast#nodes
215+
216+
[dom]: https://developer.mozilla.org/docs/Web/API/Document_Object_Model
217+
161218
[hast-util-from-parse5]: https://github.com/syntax-tree/hast-util-from-parse5
162219

163-
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
220+
[hast-util-to-dom]: https://github.com/syntax-tree/hast-util-to-dom
221+
222+
[rehype-dom-parse]: https://github.com/rehypejs/rehype-dom/tree/main/packages/rehype-dom-parse
164223

165-
[sanitize]: https://github.com/syntax-tree/hast-util-sanitize
224+
[jsdom]: https://github.com/jsdom/jsdom

0 commit comments

Comments
 (0)