Skip to content

Commit f359d5d

Browse files
wooormwooorm
committed
Add improved docs
1 parent 30ebfae commit f359d5d

File tree

1 file changed

+98
-38
lines changed

1 file changed

+98
-38
lines changed

‎readme.md

Lines changed: 98 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -8,22 +8,61 @@
88
[![Backers][backers-badge]][collective]
99
[![Chat][chat-badge]][chat]
1010

11-
**[hast][]** utility to transform a *[tree][]* to **[estree][]** JSX.
11+
[hast][] utility to transform to [estree][] (JSX).
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+
* [`toEstree(tree, options?)`](#toestreetree-options)
21+
* [Types](#types)
22+
* [Compatibility](#compatibility)
23+
* [Security](#security)
24+
* [Related](#related)
25+
* [Contribute](#contribute)
26+
* [License](#license)
27+
28+
## What is this?
29+
30+
This package is a utility that takes a [hast][] (HTML) syntax tree as input and
31+
turns it into an [estree][] (JavaScript) syntax tree JSX extension.
32+
This package also supports embedded MDX nodes.
1433

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.
34+
## When should I use this?
1735

18-
[npm][]:
36+
This project is useful when you want to embed HTML as JSX inside JS while
37+
working with syntax trees.
38+
This us used in [MDX][].
39+
40+
## Install
41+
42+
This package is [ESM only][esm].
43+
In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with [npm][]:
1944

2045
```sh
2146
npm install hast-util-to-estree
2247
```
2348

49+
In Deno with [`esm.sh`][esmsh]:
50+
51+
```js
52+
import {toEstree} from 'https://esm.sh/hast-util-to-estree@2'
53+
```
54+
55+
In browsers with [`esm.sh`][esmsh]:
56+
57+
```html
58+
<script type="module">
59+
import {toEstree} from 'https://esm.sh/hast-util-to-estree@2?bundle'
60+
</script>
61+
```
62+
2463
## Use
2564

26-
Say we have the following HTML file, `example.html`:
65+
Say our module `example.html` contains:
2766

2867
```html
2968
<!doctype html>
@@ -45,24 +84,24 @@ Say we have the following HTML file, `example.html`:
4584
<script src="index.js"></script>
4685
```
4786

48-
And our script, `example.js`, is:
87+
…and our module `example.js` looks as follows:
4988

5089
```js
51-
import fs from 'node:fs'
90+
import fs from 'node:fs/promises'
5291
import parse5 from 'parse5'
5392
import {fromParse5} from 'hast-util-from-parse5'
5493
import {toEstree} from 'hast-util-to-estree'
5594
import recast from 'recast'
5695

57-
const hast = fromParse5(parse5.parse(String(fs.readFileSync('example.html'))))
96+
const hast = fromParse5(parse5.parse(String(await fs.readFile('example.html'))))
5897

5998
const estree = toEstree(hast)
6099

61100
estree.comments = null // `recast` doesn’t like comments on the root.
62101
console.log(recast.prettyPrint(estree).code)
63102
```
64103

65-
Now, `node example` (and prettier), yields:
104+
…now running `node example.js` (and prettier) yields:
66105

67106
```jsx
68107
;<>
@@ -78,10 +117,7 @@ Now, `node example` (and prettier), yields:
78117
{'\n'}
79118
<a
80119
download
81-
style={{
82-
width: '1',
83-
height: '10px'
84-
}}
120+
style={{width: '1', height: '10px'}}
85121
/>
86122
{'\n'}
87123
{/*commentz*/}
@@ -103,26 +139,34 @@ Now, `node example` (and prettier), yields:
103139

104140
## API
105141

106-
This package exports the following identifiers: `toEstree`.
142+
This package exports the identifier `toEstree`.
107143
There is no default export.
108144

109145
### `toEstree(tree, options?)`
110146

111-
Transform a **[hast][]** *[tree][]* to an **[estree][]** (JSX).
147+
Transform to [estree][] (JSX).
112148

113149
##### `options`
114150

115-
* `space` (enum, `'svg'` or `'html'`, default: `'html'`)
116-
— Whether node is in the `'html'` or `'svg'` space.
117-
If an `svg` element is found when inside the HTML space, `toEstree`
118-
automatically switches to the SVG space when entering the element, and
119-
switches back when exiting
151+
Configuration (optional).
152+
153+
##### `options.space`
154+
155+
Whether `tree` is in the HTML or SVG space (enum, `'svg'` or `'html'`, default:
156+
`'html'`).
157+
If an `svg` element is found when inside the HTML space, `toEstree`
158+
automatically switches to the SVG space when entering the element, and
159+
switches back when exiting
160+
161+
###### `options.handlers`
162+
163+
Object mapping node types to functions handling the corresponding nodes.
164+
See the code for examples.
120165

121166
###### Returns
122167

123-
**[estree][]** — a *[Program][]* node, whose last child in `body` is most
124-
likely an `ExpressionStatement` whose expression is a `JSXFragment` or a
125-
`JSXElement`.
168+
Node ([`Program`][program]) whose last child in `body` is most likely an
169+
`ExpressionStatement`, whose expression is a `JSXFragment` or a `JSXElement`.
126170

127171
Typically, there is only one node in `body`, however, this utility also supports
128172
embedded MDX nodes in the HTML (when [`mdast-util-mdx`][mdast-util-mdx] is used
@@ -142,6 +186,18 @@ There aren’t many great estree serializers out there that support JSX.
142186
Or use [`estree-util-build-jsx`][build-jsx] to turn JSX into function
143187
calls and then serialize with whatever (astring, escodegen).
144188

189+
## Types
190+
191+
This package is fully typed with [TypeScript][].
192+
It exports the additional types `Options`, `Space`, and `Handle`.
193+
194+
## Compatibility
195+
196+
Projects maintained by the unified collective are compatible with all maintained
197+
versions of Node.js.
198+
As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
199+
Our projects sometimes work with older versions, but this is not guaranteed.
200+
145201
## Security
146202

147203
You’re working with JavaScript.
@@ -150,20 +206,16 @@ It’s not safe.
150206
## Related
151207

152208
* [`hastscript`][hastscript]
153-
— Hyperscript compatible interface for creating nodes
209+
— hyperscript compatible interface for creating nodes
154210
* [`hast-util-from-dom`](https://github.com/syntax-tree/hast-util-from-dom)
155-
— Transform a DOM tree to hast
156-
* [`unist-builder`](https://github.com/syntax-tree/unist-builder)
157-
— Create any unist tree
158-
* [`xastscript`](https://github.com/syntax-tree/xastscript)
159-
— Create a xast tree
211+
— transform a DOM tree to hast
160212
* [`estree-util-build-jsx`][build-jsx]
161-
— Transform JSX to function calls
213+
— transform JSX to function calls
162214

163215
## Contribute
164216

165-
See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
166-
started.
217+
See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
218+
ways to get started.
167219
See [`support.md`][support] for ways to get help.
168220

169221
This project has a [code of conduct][coc].
@@ -204,19 +256,25 @@ abide by its terms.
204256

205257
[npm]: https://docs.npmjs.com/cli/install
206258

259+
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
260+
261+
[esmsh]: https://esm.sh
262+
263+
[typescript]: https://www.typescriptlang.org
264+
207265
[license]: license
208266

209267
[author]: https://wooorm.com
210268

211-
[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
269+
[health]: https://github.com/syntax-tree/.github
212270

213-
[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
271+
[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
214272

215-
[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
273+
[support]: https://github.com/syntax-tree/.github/blob/main/support.md
216274

217-
[hastscript]: https://github.com/syntax-tree/hastscript
275+
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
218276

219-
[tree]: https://github.com/syntax-tree/unist#tree
277+
[hastscript]: https://github.com/syntax-tree/hastscript
220278

221279
[hast]: https://github.com/syntax-tree/hast
222280

@@ -229,3 +287,5 @@ abide by its terms.
229287
[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx
230288

231289
[build-jsx]: https://github.com/wooorm/estree-util-build-jsx
290+
291+
[mdx]: https://mdxjs.com

0 commit comments

Comments
 (0)