Skip to content

Commit 099ea89

Browse files
wooormwooorm
committed
Add improved docs
1 parent 450ad02 commit 099ea89

File tree

1 file changed

+94
-39
lines changed

1 file changed

+94
-39
lines changed

‎readme.md

Lines changed: 94 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -8,34 +8,77 @@
88
[![Backers][backers-badge]][collective]
99
[![Chat][chat-badge]][chat]
1010

11-
**[hast][]** (HTML / SVG) utility to transform *[trees][tree]* to **[xast][]**
12-
(XML).
11+
[hast][] (HTML) utility to transform to [xast][] (XML).
1312

14-
## 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+
* [`toXast(node[, space|options])`](#toxastnode-spaceoptions)
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 a [xast][] (XML) syntax tree.
32+
This package also supports embedded MDX nodes.
33+
34+
## When should I use this?
35+
36+
This project is useful when you want to deal with ASTs, and for some reason,
37+
*have* to deal with XML.
38+
One example of this is for EPUB (digital books).
39+
40+
There is no inverse of this utility, because not all XML is HTML.
41+
42+
A similar package, [`hast-util-to-estree`][hast-util-to-estree], can turn
43+
hast into estree (JavaScript) as JSX, which has some similarities to XML.
1544

16-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
17-
Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
45+
## Install
1846

19-
[npm][]:
47+
This package is [ESM only][esm].
48+
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
2049

2150
```sh
2251
npm install hast-util-to-xast
2352
```
2453

54+
In Deno with [`esm.sh`][esmsh]:
55+
56+
```js
57+
import {toXast} from "https://esm.sh/hast-util-to-xast@2"
58+
```
59+
60+
In browsers with [`esm.sh`][esmsh]:
61+
62+
```html
63+
<script type="module">
64+
import {toXast} from "https://esm.sh/hast-util-to-xast@2?bundle"
65+
</script>
66+
```
67+
2568
## Use
2669

27-
Say we have an `example.html` file, that looks as follows:
70+
Say our document `example.html` contains:
2871

2972
```html
3073
<!doctypehtml>
3174
<title>Hello, World!</title>
3275
<h1>👋, 🌍</h1>
3376
```
3477

35-
…and our script, `example.js`, looks as follows:
78+
…and our module `example.js` looks as follows:
3679

3780
```js
38-
import fs from 'node:fs'
81+
import fs from 'node:fs/promises'
3982
import {unified} from 'unified'
4083
import rehypeParse from 'rehype-parse'
4184
import {toXast} from 'hast-util-to-xast'
@@ -44,7 +87,7 @@ import {toXml} from 'xast-util-to-xml'
4487
// Get the HTML syntax tree:
4588
const hast = unified()
4689
.use(rehypeParse)
47-
.parse(fs.readFileSync('example.html'))
90+
.parse(await fs.readFile('example.html'))
4891

4992
// Turn hast to xast:
5093
const xast = toXast(hast)
@@ -53,7 +96,7 @@ const xast = toXast(hast)
5396
console.log(toXml(xast))
5497
```
5598

56-
Yields:
99+
…now running `node example.js` yields:
57100

58101
```xml
59102
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"><head><title>Hello, World!</title>
@@ -63,51 +106,59 @@ Yields:
63106

64107
## API
65108

66-
This package exports the following identifiers: `toXast`.
109+
This package exports the identifier `toXast`.
67110
There is no default export.
68111

69112
### `toXast(node[, space|options])`
70113

71-
Transform the given **[hast][]** *[tree][]* to **[xast][]**.
72-
73-
##### `space`
74-
75-
Treated as `options.space`.
114+
[hast][] utility to transform to [xast][].
76115

77116
##### `options`
78117

118+
Configuration (optional).
119+
79120
###### `options.space`
80121

81-
Whether the [*root*][root] of the [*tree*][tree] is in the `'html'` or `'svg'`
82-
space (enum, `'svg'` or `'html'`, default: `'html'`).
122+
Whether the given `node` is in the HTML or SVG space (enum, `'svg'` or `'html'`,
123+
default: `'html'`).
83124

84125
If an `svg` element is found in the HTML space, `toXast` automatically switches
85126
to the SVG space when entering the element, and switches back when exiting.
86127

87128
You can also switch explicitly with `xmlns` properties in hast, but note that
88129
only HTML and SVG are supported.
89130

131+
## Types
132+
133+
This package is fully typed with [TypeScript][].
134+
It exports the additional types `Options` and `Space`.
135+
136+
## Compatibility
137+
138+
Projects maintained by the unified collective are compatible with all maintained
139+
versions of Node.js.
140+
As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
141+
Our projects sometimes work with older versions, but this is not guaranteed.
142+
90143
## Security
91144

92-
Both HTML and XML can be a dangerous language: don’t trust user-provided data.
93-
Use [`hast-util-santize`][sanitize] to make the hast tree safe before using this
94-
utility.
145+
Both HTML and XML can be dangerous languages: don’t trust user-provided data.
146+
Use [`hast-util-santize`][hast-util-sanitize] to make the hast tree safe before
147+
using this utility.
95148

96149
## Related
97150

98-
* [`unist-builder`][u]
99-
— Create any unist tree
100151
* [`hastscript`][h]
101-
— Create a **[hast][]** (HTML or SVG) tree
152+
— create **[hast][]** (HTML or SVG) trees
102153
* [`xastscript`][x]
103-
— Create a **[xast][]** (XML) tree
154+
— create **[xast][]** (XML) trees
104155
* [`xast-util-to-xml`](https://github.com/syntax-tree/xast-util-to-xml)
105-
— Serialize nodes to XML
156+
— serialize as XML
106157

107158
## Contribute
108159

109-
See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
110-
started.
160+
See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
161+
ways to get started.
111162
See [`support.md`][support] for ways to get help.
112163

113164
This project has a [code of conduct][coc].
@@ -148,28 +199,32 @@ abide by its terms.
148199

149200
[npm]: https://docs.npmjs.com/cli/install
150201

202+
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
203+
204+
[esmsh]: https://esm.sh
205+
206+
[typescript]: https://www.typescriptlang.org
207+
151208
[license]: license
152209

153210
[author]: https://wooorm.com
154211

155-
[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
212+
[health]: https://github.com/syntax-tree/.github
213+
214+
[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
156215

157-
[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
216+
[support]: https://github.com/syntax-tree/.github/blob/main/support.md
158217

159-
[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
218+
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
160219

161220
[hast]: https://github.com/syntax-tree/hast
162221

163222
[xast]: https://github.com/syntax-tree/xast
164223

165-
[tree]: https://github.com/syntax-tree/unist#tree
166-
167-
[root]: https://github.com/syntax-tree/unist#root
168-
169-
[sanitize]: https://github.com/syntax-tree/hast-util-sanitize
170-
171-
[u]: https://github.com/syntax-tree/unist-builder
224+
[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize
172225

173226
[h]: https://github.com/syntax-tree/hastscript
174227

175228
[x]: https://github.com/syntax-tree/xastscript
229+
230+
[hast-util-to-estree]: https://github.com/syntax-tree/hast-util-to-estree

0 commit comments

Comments
 (0)