Skip to content

Commit 5e3609a

Browse files
wooormwooorm
committed
Add improved docs
1 parent d47e132 commit 5e3609a

File tree

2 files changed

+117
-62
lines changed

2 files changed

+117
-62
lines changed

Diff for: ‎lib/index.js

+3-3
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,11 @@
1818
* @typedef Options
1919
* Configuration (optional).
2020
* @property {boolean} [fragment=false]
21-
* Whether a DOM fragment should be returned
21+
* Return a DOM fragment, creates whole documents otherwise.
2222
* @property {Document} [document]
23-
* Document interface to use (default: `globalThis.document`)
23+
* Document interface to use (default: `globalThis.document`).
2424
* @property {string} [namespace]
25-
* `namespace` to use to create elements
25+
* `namespace` to use to create elements.
2626
* @property {AfterTransform} [afterTransform]
2727
* Callback invoked after each node transformation
2828
*

Diff for: ‎readme.md

+114-59
Original file line numberDiff line numberDiff line change
@@ -8,115 +8,158 @@
88
[![Backers][backers-badge]][collective]
99
[![Chat][chat-badge]][chat]
1010

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

13-
## Install
13+
## Contents
1414

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.
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+
* [`toDom(node[, options])`](#todomnode-options)
21+
* [Types](#types)
22+
* [Compatibility](#compatibility)
23+
* [Security](#security)
24+
* [Related](#related)
25+
* [Contribute](#contribute)
26+
* [License](#license)
1727

18-
[npm][]:
28+
## What is this?
1929

20-
```sh
21-
npm install hast-util-to-dom
22-
```
30+
This package is a utility that creates a DOM tree (defaulting to the actual DOM
31+
but also supporting things like [`jsdom`][jsdom]) from a [hast][] (HTML) syntax
32+
tree.
2333

24-
## Use
34+
## When should I use this?
2535

26-
This utility is intended for browser use!
36+
You can use this project when you want to turn hast into a DOM in browsers,
37+
either to use it directly on a page, or to enable the use of DOM APIs (such as
38+
`querySelector` to find things or `innerHTML` to serialize stuff).
2739

28-
```js
29-
import {toDom} from 'hast-util-to-dom';
40+
The hast utility [`hast-util-from-dom`][hast-util-from-dom] does the inverse of
41+
this utility.
42+
It turns DOM trees into hast.
3043

31-
const el = toDom({
32-
type: 'element',
33-
tagName: 'h1',
34-
properties: {},
35-
children: [{type: 'text', value: 'World!'}]
36-
});
44+
The rehype plugin [`rehype-dom-stringify`][rehype-dom-stringify] wraps this
45+
utility to serialize as HTML with DOM APIs.
3746

38-
console.log(el);
39-
```
47+
## Install
4048

41-
This will create a DOM node like this:
49+
This package is [ESM only][esm].
50+
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
4251

43-
```html
44-
<h1>World!</h1>
52+
```sh
53+
npm install hast-util-from-dom
4554
```
4655

47-
If you want a string of HTML, you have a few options:
56+
In Deno with [`esm.sh`][esmsh]:
4857

4958
```js
50-
// Outer HTML, eg. if you want an entire fragment
51-
console.log(el.outerHTML);
52-
// "<h1>World</h1>"
59+
import {toDom} from 'https://esm.sh/hast-util-to-dom@3'
60+
```
61+
62+
In browsers with [`esm.sh`][esmsh]:
63+
64+
```html
65+
<script type="module">
66+
import {toDom} from 'https://esm.sh/hast-util-to-dom@3?bundle'
67+
</script>
68+
```
69+
70+
## Use
5371

54-
// Inner HTML, eg. if you have a wrapping element you don't need
55-
console.log(el.innerHTML);
56-
// "World"
72+
Say our page `example.html` looks as follows:
5773

58-
// Full serialization, eg. when you want the whole document
59-
console.log(new XMLSerializer().serializeToString(el));
60-
// "<div xmlns="http://www.w3.org/1999/xhtml">World</div>"
74+
```html
75+
<!doctype html>
76+
<title>Example</title>
77+
<body>
78+
<script type="module">
79+
import {h} from 'https://esm.sh/hastscript?bundle'
80+
import {toDom} from 'https://esm.sh/hast-util-to-dom?bundle'
81+
82+
const tree = h('main', [
83+
h('h1', 'Hi'),
84+
h('p', [h('em', 'Hello'), ', world!'])
85+
])
86+
87+
document.body.append(toDom(tree))
88+
</script>
6189
```
6290

63-
Due to the nature of various browser implementations, you may notice
64-
cross-browser differences in the serialized output, especially with respect to
65-
whitespace or self-closing tags.
66-
Buddy, that’s the web!
91+
Now running `open example.html` shows the equivalent HTML on the page.
6792

6893
## API
6994

70-
This package exports the following identifiers: `toDom`.
95+
This package exports the identifier `toDom`.
7196
There is no default export.
7297

7398
### `toDom(node[, options])`
7499

75-
Transform a [**hast**][hast] [*tree*][tree] to a DOM tree.
100+
Turn a hast tree into a DOM tree.
76101

77102
##### `options`
78103

104+
Configuration (optional).
105+
79106
###### `options.fragment`
80107

81-
Whether a DOM fragment should be returned (default: `false`).
108+
Return a DOM fragment (`boolean`, default: `false`).
109+
Creates whole documents otherwise.
82110

83111
###### `options.document`
84112

85-
Document interface to use (default: `globalThis.document`).
113+
Document interface to use (`Document`, default: `globalThis.document`).
86114

87115
###### `options.namespace`
88116

89-
`namespace` to use to create [*elements*][element].
117+
`namespace` to use to create elements (`string?`, optional).
90118

91119
###### `options.afterTransform`
92120

93-
Function called after a hast node is transformed into a DOM node (`Function?`).
94-
Given the hast node that was handled as the first parameter and the
95-
corresponding DOM node as the second parameter.
121+
Called when a hast node was transformed into a DOM node
122+
(`(HastNode, Node) => void?`, optional).
123+
124+
##### Returns
125+
126+
[`Node`][dom].
127+
128+
## Types
129+
130+
This package is fully typed with [TypeScript][].
131+
It exports the additional type `Options`.
132+
133+
## Compatibility
134+
135+
Projects maintained by the unified collective are compatible with all maintained
136+
versions of Node.js.
137+
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
138+
Our projects sometimes work with older versions, but this is not guaranteed.
96139

97140
## Security
98141

99142
Use of `hast-util-to-dom` can open you up to a
100143
[cross-site scripting (XSS)][xss] attack if the hast tree is unsafe.
101-
Use [`hast-util-santize`][sanitize] to make the hast tree safe.
144+
Use [`hast-util-santize`][hast-util-sanitize] to make the hast tree safe.
102145

103146
## Related
104147

105148
* [`hast-util-sanitize`](https://github.com/syntax-tree/hast-util-sanitize)
106-
— Sanitize hast nodes
149+
— sanitize hast nodes
107150
* [`hast-util-to-html`](https://github.com/syntax-tree/hast-util-to-html)
108-
— Create an HTML string
151+
— serialize as HTML
109152
* [`hast-util-from-dom`](https://github.com/syntax-tree/hast-util-from-dom)
110-
— Create a hast tree from a DOM tree
153+
— create a hast tree from a DOM tree
111154

112155
## Contribute
113156

114-
See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
115-
started.
157+
See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
158+
ways to get started.
116159
See [`support.md`][support] for ways to get help.
117160

118161
This project has a [code of conduct][coc].
119-
By interacting with this repository, organization, or community you agree to
162+
By interacting with this repository, organisation, or community you agree to
120163
abide by its terms.
121164

122165
## License
@@ -153,22 +196,34 @@ abide by its terms.
153196

154197
[npm]: https://docs.npmjs.com/cli/install
155198

199+
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
200+
201+
[esmsh]: https://esm.sh
202+
203+
[typescript]: https://www.typescriptlang.org
204+
156205
[license]: license
157206

158207
[author]: https://keith.mcknig.ht
159208

160-
[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
209+
[health]: https://github.com/syntax-tree/.github
161210

162-
[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
211+
[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
163212

164-
[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
213+
[support]: https://github.com/syntax-tree/.github/blob/main/support.md
165214

166-
[hast]: https://github.com/syntax-tree/hast
215+
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
167216

168-
[element]: https://github.com/syntax-tree/hast#element
217+
[hast]: https://github.com/syntax-tree/hast
169218

170-
[tree]: https://github.com/syntax-tree/unist#tree
219+
[dom]: https://developer.mozilla.org/docs/Web/API/Document_Object_Model
171220

172221
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
173222

174-
[sanitize]: https://github.com/syntax-tree/hast-util-sanitize
223+
[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize
224+
225+
[hast-util-from-dom]: https://github.com/syntax-tree/hast-util-from-dom
226+
227+
[jsdom]: https://github.com/jsdom/jsdom
228+
229+
[rehype-dom-stringify]: https://github.com/rehypejs/rehype-dom/tree/main/packages/rehype-dom-stringify

0 commit comments

Comments
 (0)