Skip to content

Commit 6c3a52d

Browse files
wooormwooorm
committed
Add improved docs
1 parent 3ca1ead commit 6c3a52d

File tree

2 files changed

+99
-33
lines changed

2 files changed

+99
-33
lines changed

‎lib/index.js

+1-3
Original file line numberDiff line numberDiff line change
@@ -54,9 +54,7 @@
5454
* The default, when `emitParseErrors: true`, is `true` (or `1`), and means
5555
* that rules emit as warnings.
5656
* Rules can also be configured with `2`, to turn them into fatal errors.
57-
*/
58-
59-
/**
57+
*
6058
* @typedef {FromParse5Options & ParseFields & ErrorFields} Options
6159
* Configuration.
6260
*/

‎readme.md

+98-30
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,17 @@
1717
* [Install](#install)
1818
* [Use](#use)
1919
* [API](#api)
20-
* [`fromHtml(file[, options])`](#fromhtmlfile-options)
20+
* [`fromHtml(value[, options])`](#fromhtmlvalue-options)
21+
* [`Options`](#options)
22+
* [`OnError`](#onerror)
23+
* [`ErrorCode`](#errorcode)
24+
* [`ErrorSeverity`](#errorseverity)
2125
* [Examples](#examples)
2226
* [Example: fragment versus document](#example-fragment-versus-document)
2327
* [Example: whitespace around and inside `<html>`](#example-whitespace-around-and-inside-html)
2428
* [Example: parse errors](#example-parse-errors)
2529
* [Syntax](#syntax)
26-
* [Types](#types)
30+
* [Types](#types-2)
2731
* [Compatibility](#compatibility)
2832
* [Security](#security)
2933
* [Related](#related)
@@ -55,7 +59,7 @@ It turns hast into HTML.
5559
## Install
5660

5761
This package is [ESM only][esm].
58-
In Node.js (version 14.14+, 16.0+, or 18.0+), install with [npm][]:
62+
In Node.js (version 14.14+ and 16.0+), install with [npm][]:
5963

6064
```sh
6165
npm install hast-util-from-html
@@ -109,23 +113,31 @@ Yields:
109113

110114
## API
111115

112-
This package exports the identifier `fromHtml`.
116+
This package exports the identifier [`fromHtml`][fromhtml].
113117
There is no default export.
114118

115-
### `fromHtml(file[, options])`
119+
### `fromHtml(value[, options])`
116120

117-
Parse `file` ([`VFile`][vfile] or anything that can be given to `VFile`) as hast
118-
([`Root`][root]).
121+
Turn serialized HTML into a hast tree.
119122

120-
##### `options`
123+
###### Parameters
121124

122-
Configuration (optional).
125+
<!-- To do: update link when `vfile` has new docs. -->
123126

124-
###### `options.fragment`
127+
* `value` ([`Compatible`][compatible])
128+
— serialized HTML to parse
129+
* `options` ([`Options`][options], optional)
130+
— configuration
125131

126-
Whether to parse as a fragment (`boolean`, default: `false`).
127-
The default is to expect a whole document.
128-
In document mode, unopened `html`, `head`, and `body` elements are opened.
132+
###### Returns
133+
134+
Tree ([`Root`][root]).
135+
136+
### `Options`
137+
138+
Configuration (TypeScript type).
139+
140+
##### Fields
129141

130142
###### `options.space`
131143

@@ -146,19 +158,24 @@ exiting it.
146158
###### `options.verbose`
147159

148160
Add extra positional info about attributes, start tags, and end tags
149-
(`boolean`, default: `false`)
161+
(`boolean`, default: `false`).
162+
163+
###### `options.fragment`
164+
165+
Whether to parse as a fragment (`boolean`, default: `false`).
166+
The default is to expect a whole document.
167+
In document mode, unopened `html`, `head`, and `body` elements are opened.
150168

151169
###### `options.onerror`
152170

153171
Function called when encountering [HTML parse errors][parse-errors]
154-
(`(error: VFileMessage) => void`, optional).
155-
Called with a [`VFileMessage`][vfile-message].
172+
([`OnError`][onerror], optional).
156173

157-
Specific rules can be turned off by setting their identifiers directly in
158-
`options` to `false` (or `0`).
159-
The default, when `onerror` is passed, is `true` (or `1`), and means that
160-
messages are warnings.
161-
Rules can also be configured with `2`, to turn them into fatal errors.
174+
###### `options[key in ErrorCode]`
175+
176+
Specific parse errors can be configured by setting their identifiers (see
177+
[`ErrorCode`][errorcode]) as keys directly in `options` to an
178+
[`ErrorSeverity`][errorseverity] as value.
162179

163180
The list of parse errors:
164181

@@ -227,9 +244,50 @@ The list of parse errors:
227244

228245
<!-- parse-error end -->
229246

230-
##### Returns
247+
### `OnError`
231248

232-
Tree ([`Root`][root]).
249+
Function called when encountering [HTML parse errors][parse-errors].
250+
251+
###### Parameters
252+
253+
* `error` ([`VFileMessage`][vfilemessage])
254+
— message
255+
256+
###### Returns
257+
258+
Nothing (`void`).
259+
260+
### `ErrorCode`
261+
262+
Known names of parse errors (TypeScript type).
263+
264+
###### Types
265+
266+
```ts
267+
type ErrorCode =
268+
| 'abandonedHeadElementChild'
269+
| 'abruptClosingOfEmptyComment'
270+
| 'abruptDoctypePublicIdentifier'
271+
// … see readme on `options[key in ErrorCode]` above.
272+
```
273+
274+
### `ErrorSeverity`
275+
276+
Error severity (TypeScript type).
277+
278+
###### Types
279+
280+
```ts
281+
export type ErrorSeverity =
282+
// Turn the parse error off:
283+
| 0
284+
| false
285+
// Turn the parse error into a warning:
286+
| 1
287+
| true
288+
// Turn the parse error into an actual error: processing stops.
289+
| 2
290+
```
233291
234292
## Examples
235293
@@ -393,14 +451,14 @@ followed by browsers such as Chrome and Firefox.
393451
## Types
394452

395453
This package is fully typed with [TypeScript][].
396-
It exports the additional type `Options`, `OnError`, `ErrorCode`, and
397-
`ErrorSeverity`.
454+
It exports the additional type [`Options`][options], [`OnError`][onerror],
455+
[`ErrorCode`][errorcode], and [`ErrorSeverity`][errorseverity].
398456

399457
## Compatibility
400458

401459
Projects maintained by the unified collective are compatible with all maintained
402460
versions of Node.js.
403-
As of now, that is Node.js 14.14+, 16.0+, and 18.0+.
461+
As of now, that is Node.js 14.14+ and 16.0+.
404462
Our projects sometimes work with older versions, but this is not guaranteed.
405463

406464
## Security
@@ -494,14 +552,24 @@ abide by its terms.
494552

495553
[xast-util-from-xml]: https://github.com/syntax-tree/xast-util-from-xml
496554

497-
[vfile]: https://github.com/vfile/vfile
498-
499-
[vfile-message]: https://github.com/vfile/vfile-message
500-
501555
[rehype-parse]: https://github.com/rehypejs/rehype/tree/main/packages/rehype-parse#readme
502556

503557
[rehype-format]: https://github.com/rehypejs/rehype-format
504558

505559
[parse5]: https://github.com/inikulin/parse5
506560

507561
[parse-errors]: https://html.spec.whatwg.org/multipage/parsing.html#parse-errors
562+
563+
[vfilemessage]: https://github.com/vfile/vfile-message#vfilemessagereason-place-origin
564+
565+
[fromhtml]: #fromhtmlvalue-options
566+
567+
[options]: #options
568+
569+
[onerror]: #onerror
570+
571+
[errorcode]: #errorcode
572+
573+
[errorseverity]: #errorseverity
574+
575+
[compatible]: https://github.com/vfile/vfile/blob/03efac7/lib/index.js#L16

0 commit comments

Comments
 (0)