diff --git a/package.json b/package.json
index 5da980f8..797e32ec 100644
--- a/package.json
+++ b/package.json
@@ -95,7 +95,11 @@
},
"remarkConfig": {
"plugins": [
- "preset-wooorm"
+ "preset-wooorm",
+ [
+ "remark-lint-no-html",
+ false
+ ]
]
},
"typeCoverage": {
diff --git a/readme.md b/readme.md
index c1311510..987cfdc3 100644
--- a/readme.md
+++ b/readme.md
@@ -8,112 +8,99 @@
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]
-**unified** is an interface for processing text using syntax trees.
-It’s what powers [**remark**][remark] (Markdown), [**retext**][retext] (natural
-language), and [**rehype**][rehype] (HTML), and allows for processing between
-formats.
-
-## Intro
-
-**unified** enables new exciting projects like [Gatsby][] to pull in Markdown,
-[MDX][] to embed [JSX][], and [Prettier][] to format it.
-It’s used in about 700k projects on GitHub and has about 35m downloads each
-month on npm: you’re probably using it.
-Some notable users are [Node.js][], [Vercel][], [Netlify][], [GitHub][],
-[Mozilla][], [WordPress][], [Adobe][], [Facebook][], [Google][], and many more.
-
-* To read about what we are up to, follow us [Twitter][]
-* For a less technical and more practical introduction to unified, visit
- [`unifiedjs.com`][site] and peruse its [Learn][] section
-* Browse [awesome unified][awesome] to find out more about the ecosystem
-* Questions?
- Get help on [Discussions][chat]!
-* Check out [Contribute][] below to find out how to help out, or become a
- backer or sponsor on [OpenCollective][collective]
-
-## Sponsors
+**unified** lets you inspect and transform content with plugins.
-Support this effort and give back by sponsoring on [OpenCollective][collective]!
+## Contents
-
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [Overview](#overview)
+* [API](#api)
+ * [`processor()`](#processor)
+ * [`processor.use(plugin[, options])`](#processoruseplugin-options)
+ * [`processor.parse(file)`](#processorparsefile)
+ * [`processor.stringify(tree[, file])`](#processorstringifytree-file)
+ * [`processor.run(tree[, file][, done])`](#processorruntree-file-done)
+ * [`processor.runSync(tree[, file])`](#processorrunsynctree-file)
+ * [`processor.process(file[, done])`](#processorprocessfile-done)
+ * [`processor.processSync(file)`](#processorprocesssyncfile)
+ * [`processor.data([key[, value]])`](#processordatakey-value)
+ * [`processor.freeze()`](#processorfreeze)
+* [`Plugin`](#plugin)
+ * [`function attacher(options?)`](#function-attacheroptions)
+ * [`function transformer(tree, file[, next])`](#function-transformertree-file-next)
+* [`Preset`](#preset)
+* [Types](#types)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [Sponsor](#sponsor)
+* [Acknowledgments](#acknowledgments)
+* [License](#license)
-
+## What is this?
-## Install
+unified is two things:
+
+* **unified** is a collective of 500+ free and open source packages that work
+ with content as structured data (ASTs)
+* `unified` (this project) is the core package, used in 800k+ projects on GH,
+ to process content with plugins
-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.
+Several ecosystems are built on unified around different kinds of content.
+Notably, [remark][] (markdown), [rehype][] (HTML), and [retext][] (natural
+language).
+These ecosystems can be connected together.
-[npm][]:
+* for more about us, see [`unifiedjs.com`][site]
+* for updates, see [@unifiedjs][twitter] on Twitter
+* for questions, see [support][]
+* to help, see [contribute][] and [sponsor][] below
+
+## When should I use this?
+
+In some cases, you are already using unified.
+For example, it’s used in MDX, Gatsby, Docusaurus, etc.
+In those cases, you don’t need to add `unified` yourself but you can include
+plugins into those projects.
+
+But the real fun (for some) is to get your hands dirty and work with syntax
+trees and build with it yourself.
+You can create those projects, or things like Prettier, or your own site
+generator.
+You can connect utilities together and make your own plugins that check for
+problems and transform from one thing to another.
+
+When you are dealing with one type of content (such as markdown), it’s
+recommended to use the main package of that ecosystem instead (so `remark`).
+When you are dealing with different kinds of content (such as markdown and
+HTML), it’s recommended to use `unified` itself, and pick and choose the plugins
+you need.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with [npm][]:
```sh
npm install unified
```
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {unified} from 'https://esm.sh/unified@10'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+
+```
+
## Use
```js
@@ -125,23 +112,16 @@ import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import {reporter} from 'vfile-reporter'
-unified()
+const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeDocument, {title: '👋🌍'})
.use(rehypeFormat)
.use(rehypeStringify)
.process('# Hello world!')
- .then(
- (file) => {
- console.error(reporter(file))
- console.log(String(file))
- },
- (error) => {
- // Handle your error here!
- throw error
- }
- )
+
+console.error(reporter(file))
+console.log(String(file))
```
Yields:
@@ -164,37 +144,19 @@ no issues found
-
-
-
-
-
-
-
-
-
-
-
-