diff --git a/readme.md b/readme.md
index 4d1bdc0..314f7c0 100644
--- a/readme.md
+++ b/readme.md
@@ -8,25 +8,78 @@
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]
-[**rehype**][rehype] plugin to bridge or mutate to [**retext**][retext].
-
-Uses [`hast-util-to-nlcst`][to-nlcst] under the hood.
-See its documentation to learn how to ignore nodes.
+**[rehype][]** plugin to support **[retext][]**.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(rehypeRetext, destination)`](#unifieduserehyperetext-destination)
+* [Types](#types)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Related](#related)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package is a [unified][] ([rehype][]) plugin to support [retext][].
+
+**unified** is a project that transforms content with abstract syntax trees
+(ASTs).
+**rehype** adds support for HTML to unified.
+**retext** adds support for natural language to unified.
+**hast** is the HTML AST that rehype uses.
+**nlcst** is the natural language AST that retext uses.
+This is a rehype plugin that transforms hast into nlcst to support retext.
+
+## When should I use this?
+
+This project is useful if you want to check natural language in HTML.
+The retext ecosystem has many useful plugins to check prose, such as
+[`retext-indefinite-article`][retext-indefinite-article] which checks that `a`
+and `an` are used correctly, or [`retext-readability`][retext-readability] which
+checks that sentences are not too complex.
+This plugins lets you use them on HTML documents.
+
+This plugin is not able to apply changes by retext plugins (such
+as done by `retext-smartypants`) to the HTML content.
+
+This plugin is built on [`hast-util-to-nlcst`][hast-util-to-nlcst], which does
+the work on syntax trees.
+rehype focusses on making it easier to transform content by abstracting such
+internals away.
## Install
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
-Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
-
-[npm][]:
+This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
```sh
npm install rehype-retext
```
+In Deno with [Skypack][]:
+
+```js
+import rehypeRetext from 'https://cdn.skypack.dev/rehype-retext@3?dts'
+```
+
+In browsers with [Skypack][]:
+
+```html
+
+```
+
## Use
-Say `example.html` looks as follows:
+Say we have the following file `example.html`:
```html
@@ -38,10 +91,10 @@ Say `example.html` looks as follows:
```
-…and `example.js` like this:
+And our module `example.js` looks as follows:
```js
-import {readSync} from 'to-vfile'
+import {read} from 'to-vfile'
import {reporter} from 'vfile-reporter'
import {unified} from 'unified'
import rehypeParse from 'rehype-parse'
@@ -52,27 +105,28 @@ import retextEnglish from 'retext-english'
import retextIndefiniteArticle from 'retext-indefinite-article'
import retextRepeatedWords from 'retext-repeated-words'
-const file = readSync('example.html')
-
-unified()
- .use(rehypeParse)
- .use(
- rehypeRetext,
- unified()
- .use(retextEnglish)
- .use(retextIndefiniteArticle)
- .use(retextRepeatedWords)
- )
- .use(rehypePresetMinify)
- .use(rehypeStringify)
- .process(file)
- .then((file) => {
- console.error(reporter(file))
- console.log(String(file))
- })
+main()
+
+async function main() {
+ const file = await unified()
+ .use(rehypeParse)
+ .use(
+ rehypeRetext,
+ unified()
+ .use(retextEnglish)
+ .use(retextIndefiniteArticle)
+ .use(retextRepeatedWords)
+ )
+ .use(rehypePresetMinify)
+ .use(rehypeStringify)
+ .process(await read('example.html'))
+
+ console.error(reporter(file))
+ console.log(String(file))
+}
```
-Now, running `node example` yields:
+Now running `node example.js` yields:
```html
example.html
@@ -80,6 +134,9 @@ example.html
6:12-6:19 warning Expected `and` once, not twice and retext-repeated-words
⚠ 2 warnings
+```
+
+```html
Hello!A implicit sentence.This and and that.
```
@@ -90,26 +147,42 @@ The default export is `rehypeRetext`.
### `unified().use(rehypeRetext, destination)`
-[**rehype**][rehype] ([hast][]) plugin to bridge or mutate to
-[**retext**][retext] ([nlcst][]).
+**[rehype][]** plugin to support **[retext][]**.
+There are no options but `destination` is required.
###### `destination`
`destination` is either a parser or a processor.
-If a processor ([`Unified`][processor]) is given, runs the destination
-processor with the new nlcst tree, then, after running discards that tree and
-continues on running the origin processor with the original tree
-([bridge-mode][bridge]).
-
-If a parser (such as [**parse-latin**][latin], [**parse-english**][english], or
-[**parse-dutch**][dutch]) is given, passes the tree to further plugins
-(mutate-mode).
+* If a destination [processor][] is given, runs the plugins attached to it
+ with the new nlcst tree ([*bridge mode*][bridge]).
+ This given processor must have a parser attached (this can be done by using
+ the plugin `retext-english` or similar) and should use other retext plugins
+* If a parser is given, runs further plugins attached to the same processor
+ with the new tree (*mutate mode*).
+ Such parsers are exported by packages like `retext-english` as `Parser`.
+ You should use other retext plugins after `rehype-retext`.
As HTML defines paragraphs, that definition is used for
[**Paragraph**][paragraph]s: `` and `` are explicitly
supported, and implicit paragraphs in flow content are also supported.
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the `Parser` and `Processor` types, which specify the interfaces of
+the accepted destination.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with all maintained
+versions of Node.js.
+As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
+Our projects sometimes work with older versions, but this is not guaranteed.
+
+This plugin works with `unified` version 6+, `rehype` version 4+, and `retext`
+version 7+.
+
## Security
`rehype-retext` does not change the syntax tree so there are no openings for
@@ -118,12 +191,11 @@ supported, and implicit paragraphs in flow content are also supported.
## Related
* [`rehype-remark`](https://github.com/rehypejs/rehype-remark)
- — Transform HTML ([**hast**][hast]) to Markdown ([**mdast**][mdast])
+ — rehype plugin to turn HTML into markdown
* [`remark-retext`](https://github.com/remarkjs/remark-retext)
- — Transform Markdown ([**mdast**][mdast]) to natural language
- ([**nlcst**][nlcst])
+ — remark plugin to support retext
* [`remark-rehype`](https://github.com/remarkjs/remark-rehype)
- — Transform Markdown ([**mdast**][mdast]) to HTML ([**hast**][hast])
+ — remark plugin to turn markdown into HTML
## Contribute
@@ -169,6 +241,8 @@ abide by its terms.
[npm]: https://docs.npmjs.com/cli/install
+[skypack]: https://www.skypack.dev
+
[health]: https://github.com/rehypejs/.github
[contributing]: https://github.com/rehypejs/.github/blob/HEAD/contributing.md
@@ -181,6 +255,10 @@ abide by its terms.
[author]: https://wooorm.com
+[typescript]: https://www.typescriptlang.org
+
+[unified]: https://github.com/unifiedjs/unified
+
[rehype]: https://github.com/rehypejs/rehype
[retext]: https://github.com/retextjs/retext
@@ -189,20 +267,12 @@ abide by its terms.
[bridge]: https://github.com/unifiedjs/unified#processing-between-syntaxes
-[hast]: https://github.com/syntax-tree/hast
-
-[mdast]: https://github.com/syntax-tree/mdast
-
-[nlcst]: https://github.com/syntax-tree/nlcst
-
[paragraph]: https://github.com/syntax-tree/nlcst#paragraph
-[to-nlcst]: https://github.com/syntax-tree/hast-util-to-nlcst
-
-[latin]: https://github.com/wooorm/parse-latin
+[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
-[english]: https://github.com/wooorm/parse-english
+[retext-indefinite-article]: https://github.com/retextjs/retext-indefinite-article
-[dutch]: https://github.com/wooorm/parse-dutch
+[retext-readability]: https://github.com/retextjs/retext-readability
-[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
+[hast-util-to-nlcst]: https://github.com/syntax-tree/hast-util-to-nlcst