Skip to content

Commit 82f16ab

Browse files
wooormwooorm
committed
Refactor docs
1 parent e4dff32 commit 82f16ab

File tree

2 files changed

+107
-84
lines changed

2 files changed

+107
-84
lines changed

‎lib/index.js

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,11 @@
4747
* Handle parse errors.
4848
* @param {VFileMessage} error
4949
* Message.
50-
* @returns {undefined}
50+
* @returns {undefined | void}
5151
* Nothing.
5252
*
53+
* Note: `void` included until TS infers `undefined` nicely.
54+
*
5355
* @typedef {FromParse5Options & ErrorOptions & ExtraOptions} Options
5456
* Configuration.
5557
*

‎readme.md

Lines changed: 104 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@
1818
* [Use](#use)
1919
* [API](#api)
2020
* [`fromHtml(value[, options])`](#fromhtmlvalue-options)
21-
* [`Options`](#options)
22-
* [`OnError`](#onerror)
2321
* [`ErrorCode`](#errorcode)
2422
* [`ErrorSeverity`](#errorseverity)
23+
* [`OnError`](#onerror)
24+
* [`Options`](#options)
2525
* [Examples](#examples)
2626
* [Example: fragment versus document](#example-fragment-versus-document)
2727
* [Example: whitespace around and inside `<html>`](#example-whitespace-around-and-inside-html)
@@ -42,24 +42,29 @@ tree.
4242
## When should I use this?
4343

4444
If you want to handle syntax trees manually, use this.
45+
4546
Use [`parse5`][parse5] instead when you just want to parse HTML and don’t care
4647
about [hast][].
47-
4848
You can also use [`hast-util-from-parse5`][hast-util-from-parse5] and
49-
[`parse5`][parse5] yourself manually, or use the rehype plugin
49+
[`parse5`][parse5] yourself, or use the rehype plugin
5050
[`rehype-parse`][rehype-parse], which wraps this utility to also parse HTML at
5151
a higher-level (easier) abstraction.
5252
[`xast-util-from-xml`][xast-util-from-xml] can be used if you are dealing with
5353
XML instead of HTML.
5454

55+
If you might run in a browser and prefer a ligher alternative, while not caring
56+
about positional info, parse errors, and consistency across browsers, use
57+
[`hast-util-from-html-isomorphic`][hast-util-from-html-isomorphic], which
58+
wraps this in Node and uses browser APIs otherwise.
59+
5560
Finally you can use the utility [`hast-util-to-html`][hast-util-to-html] to do
5661
the inverse of this utility.
5762
It turns hast into HTML.
5863

5964
## Install
6065

6166
This package is [ESM only][esm].
62-
In Node.js (version 14.14+ and 16.0+), install with [npm][]:
67+
In Node.js (version 16+), install with [npm][]:
6368

6469
```sh
6570
npm install hast-util-from-html
@@ -68,14 +73,14 @@ npm install hast-util-from-html
6873
In Deno with [`esm.sh`][esmsh]:
6974

7075
```js
71-
import {fromHtml} from "https://esm.sh/hast-util-from-html@1"
76+
import {fromHtml} from 'https://esm.sh/hast-util-from-html@1'
7277
```
7378

7479
In browsers with [`esm.sh`][esmsh]:
7580

7681
```html
7782
<script type="module">
78-
import {fromHtml} from "https://esm.sh/hast-util-from-html@1?bundle"
83+
import {fromHtml} from 'https://esm.sh/hast-util-from-html@1?bundle'
7984
</script>
8085
```
8186

@@ -113,7 +118,7 @@ Yields:
113118

114119
## API
115120

116-
This package exports the identifier [`fromHtml`][fromhtml].
121+
This package exports the identifier [`fromHtml`][api-from-html].
117122
There is no default export.
118123

119124
### `fromHtml(value[, options])`
@@ -126,13 +131,58 @@ Turn serialized HTML into a hast tree.
126131

127132
* `value` ([`Compatible`][compatible])
128133
— serialized HTML to parse
129-
* `options` ([`Options`][options], optional)
134+
* `options` ([`Options`][api-options], optional)
130135
— configuration
131136

132137
###### Returns
133138

134139
Tree ([`Root`][root]).
135140

141+
### `ErrorCode`
142+
143+
Known names of parse errors (TypeScript type).
144+
145+
###### Types
146+
147+
```ts
148+
type ErrorCode =
149+
| 'abandonedHeadElementChild'
150+
| 'abruptClosingOfEmptyComment'
151+
| 'abruptDoctypePublicIdentifier'
152+
// … see readme on `options[key in ErrorCode]` above.
153+
```
154+
155+
### `ErrorSeverity`
156+
157+
Error severity (TypeScript type).
158+
159+
###### Types
160+
161+
```ts
162+
export type ErrorSeverity =
163+
// Turn the parse error off:
164+
| 0
165+
| false
166+
// Turn the parse error into a warning:
167+
| 1
168+
| true
169+
// Turn the parse error into an actual error: processing stops.
170+
| 2
171+
```
172+
173+
### `OnError`
174+
175+
Function called when encountering [HTML parse errors][parse-errors].
176+
177+
###### Parameters
178+
179+
* `error` ([`VFileMessage`][vfile-message])
180+
— message
181+
182+
###### Returns
183+
184+
Nothing (`void`).
185+
136186
### `Options`
137187
138188
Configuration (TypeScript type).
@@ -141,7 +191,7 @@ Configuration (TypeScript type).
141191
142192
###### `options.space`
143193
144-
Which space the document is in (`'svg'` or `'html'`, default: `'html'`).
194+
Which space the document is in (`'html'` or `'svg'`, default: `'html'`).
145195
146196
When an `<svg>` element is found in the HTML space, `hast-util-from-html`
147197
already automatically switches to and from the SVG space when entering and
@@ -169,13 +219,13 @@ In document mode, unopened `html`, `head`, and `body` elements are opened.
169219
###### `options.onerror`
170220
171221
Function called when encountering [HTML parse errors][parse-errors]
172-
([`OnError`][onerror], optional).
222+
([`OnError`][api-on-error], optional).
173223
174224
###### `options[key in ErrorCode]`
175225
176226
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.
227+
[`ErrorCode`][api-error-code]) as keys directly in `options` to an
228+
[`ErrorSeverity`][api-error-severity] as value.
179229
180230
The list of parse errors:
181231
@@ -244,51 +294,6 @@ The list of parse errors:
244294
245295
<!-- parse-error end -->
246296
247-
### `OnError`
248-
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-
```
291-
292297
## Examples
293298
294299
### Example: fragment versus document
@@ -368,7 +373,7 @@ root[2] (1:1-9:8, 0-119)
368373
│ │ └─0 text "Hi!" (4:12-4:15, 51-54)
369374
│ └─2 text "\n " (4:23-5:3, 62-65)
370375
├─1 text "\n " (5:10-6:3, 72-75)
371-
└─2 element<body>[3] (6:3-9:8, 75-119)
376+
└─2 element<body>[3] (6:3-8:10, 75-111)
372377
│ properties: {}
373378
├─0 text "\n " (6:9-7:5, 81-86)
374379
├─1 element<h1>[1] (7:5-7:20, 86-101)
@@ -410,24 +415,34 @@ fromHtml(doc, {
410415

411416
```txt
412417
[1:10-1:10: Missing whitespace before doctype name] {
413-
reason: 'Missing whitespace before doctype name',
414-
line: 1,
418+
ancestors: undefined,
419+
cause: undefined,
415420
column: 10,
416-
source: 'parse-error',
417-
ruleId: 'missing-whitespace-before-doctype-name',
418-
position: [Object],
419421
fatal: true,
422+
line: 1,
423+
place: {
424+
start: { line: 1, column: 10, offset: 9 },
425+
end: { line: 1, column: 10, offset: 9 }
426+
},
427+
reason: 'Missing whitespace before doctype name',
428+
ruleId: 'missing-whitespace-before-doctype-name',
429+
source: 'parse-error',
420430
note: 'Unexpected `h`. Expected ASCII whitespace instead',
421431
url: 'https://html.spec.whatwg.org/multipage/parsing.html#parse-error-missing-whitespace-before-doctype-name'
422432
}
423433
[2:23-2:23: Unexpected duplicate attribute] {
424-
reason: 'Unexpected duplicate attribute',
425-
line: 2,
434+
ancestors: undefined,
435+
cause: undefined,
426436
column: 23,
427-
source: 'parse-error',
428-
ruleId: 'duplicate-attribute',
429-
position: [Object],
430437
fatal: false,
438+
line: 2,
439+
place: {
440+
start: { line: 2, column: 23, offset: 37 },
441+
end: { line: 2, column: 23, offset: 37 }
442+
},
443+
reason: 'Unexpected duplicate attribute',
444+
ruleId: 'duplicate-attribute',
445+
source: 'parse-error',
431446
note: 'Unexpectedly double attribute. Expected attributes to occur only once',
432447
url: 'https://html.spec.whatwg.org/multipage/parsing.html#parse-error-duplicate-attribute'
433448
}
@@ -451,15 +466,19 @@ followed by browsers such as Chrome and Firefox.
451466
## Types
452467

453468
This package is fully typed with [TypeScript][].
454-
It exports the additional type [`Options`][options], [`OnError`][onerror],
455-
[`ErrorCode`][errorcode], and [`ErrorSeverity`][errorseverity].
469+
It exports the additional types
470+
[`ErrorCode`][api-error-code], [`ErrorSeverity`][api-error-severity],
471+
[`OnError`][api-on-error], and [`Options`][api-options].
456472

457473
## Compatibility
458474

459-
Projects maintained by the unified collective are compatible with all maintained
475+
Projects maintained by the unified collective are compatible with maintained
460476
versions of Node.js.
461-
As of now, that is Node.js 14.14+ and 16.0+.
462-
Our projects sometimes work with older versions, but this is not guaranteed.
477+
478+
When we cut a new major release, we drop support for unmaintained versions of
479+
Node.
480+
This means we try to keep the current release line, `hast-util-from-html@^1`,
481+
compatible with Node.js 12.
463482

464483
## Security
465484

@@ -504,9 +523,9 @@ abide by its terms.
504523

505524
[downloads]: https://www.npmjs.com/package/hast-util-from-html
506525

507-
[size-badge]: https://img.shields.io/bundlephobia/minzip/hast-util-from-html.svg
526+
[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=hast-util-from-html
508527

509-
[size]: https://bundlephobia.com/result?p=hast-util-from-html
528+
[size]: https://bundlejs.com/?q=hast-util-from-html
510529

511530
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
512531

@@ -560,16 +579,18 @@ abide by its terms.
560579

561580
[parse-errors]: https://html.spec.whatwg.org/multipage/parsing.html#parse-errors
562581

563-
[vfilemessage]: https://github.com/vfile/vfile-message#vfilemessagereason-place-origin
582+
[vfile-message]: https://github.com/vfile/vfile-message#vfilemessagereason-place-origin
564583

565-
[fromhtml]: #fromhtmlvalue-options
584+
[hast-util-from-html-isomorphic]: https://github.com/syntax-tree/hast-util-from-html-isomorphic
566585

567-
[options]: #options
586+
[compatible]: https://github.com/vfile/vfile/blob/03efac7/lib/index.js#L16
568587

569-
[onerror]: #onerror
588+
[api-from-html]: #fromhtmlvalue-options
570589

571-
[errorcode]: #errorcode
590+
[api-error-code]: #errorcode
572591

573-
[errorseverity]: #errorseverity
592+
[api-error-severity]: #errorseverity
574593

575-
[compatible]: https://github.com/vfile/vfile/blob/03efac7/lib/index.js#L16
594+
[api-on-error]: #onerror
595+
596+
[api-options]: #options

0 commit comments

Comments
 (0)