Add improved docs

index.js

@@ -8,7 +8,8 @@ import {visit} from 'unist-util-visit'
 const find = /[\t ]*(?:\r?\n|\r)/g
 
 /**
- * Plugin to add hard line break support (without needing spaces or escapes).
+ * Plugin to support hard breaks without needing spaces or escapes (turns enters
+ * into `<br>`s).
  *
  * @type {import('unified').Plugin<void[], Root>}
  */

readme.md

@@ -8,26 +8,81 @@
 [![Backers][backers-badge]][collective]
 [![Chat][chat-badge]][chat]
 
-[**remark**][remark] plugin to add break support, without needing spaces.
+[**remark**][remark] plugin to support hard breaks without needing spaces or
+escapes (turns enters into `<br>`s).
+
+## 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(remarkBreaks)`](#unifieduseremarkbreaks)
+*   [Syntax](#syntax)
+*   [Syntax tree](#syntax-tree)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
+
+This package is a [unified][] ([remark][]) plugin to turn soft line endings
+(enters) into hard breaks (`<br>`s)
+
+**unified** is a project that transforms content with abstract syntax trees
+(ASTs).
+**remark** adds support for markdown to unified.
+**mdast** is the markdown AST that remark uses.
+This is a remark plugin that transforms mdast.
+
+## When should I use this?
+
+This plugin is useful if you want to display user content closer to how it was
+authored, because when a user includes a line ending, it’ll show as such.
+GitHub does this in a few places (comments, issues, PRs, and releases), but it’s
+not semantic according to HTML and not compliant to markdown.
+Markdown already has two ways to include hard breaks, namely trailing spaces and
+escapes (note that `␠` represents a normal space):
 
-## Note!
+```markdown
+lorem␠␠
+ipsum
+
+lorem\
+ipsum
+```
 
-This plugin is ready for the new parser in remark
-([`micromark`](https://github.com/micromark/micromark),
-see [`remarkjs/remark#536`](https://github.com/remarkjs/remark/pull/536)).
-A patch version was released (`2.0.1`) that works with old and new remark.
+Both will turn into `<br>`s.
+If you control who authors content or can document how markdown works, it’s
+recommended to use escapes instead.
 
 ## 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 remark-breaks
 ```
 
+In Deno with [Skypack][]:
+
+```js
+import remarkBreaks from 'https://cdn.skypack.dev/remark-breaks@3?dts'
+```
+
+In browsers with [Skypack][]:
+
+```html
+<script type="module">
+  import remarkBreaks from 'https://cdn.skypack.dev/remark-breaks@3?min'
+</script>
+```
+
 ## Use
 
 Say we have the following file, `example.md` (note: there are no spaces after
@@ -41,24 +96,25 @@ paragraph.
 And our module, `example.js`, looks as follows:
 
 ```js
-import {readSync} from 'to-vfile'
+import {read} from 'to-vfile'
 import {unified} from 'unified'
 import remarkParse from 'remark-parse'
 import remarkBreaks from 'remark-breaks'
 import remarkRehype from 'remark-rehype'
 import rehypeStringify from 'rehype-stringify'
 
-const file = readSync('example.md')
-
-unified()
-  .use(remarkParse)
-  .use(remarkBreaks)
-  .use(remarkRehype)
-  .use(rehypeStringify)
-  .process(file)
-  .then((file) => {
-    console.log(String(file))
-  })
+main()
+
+async function main() {
+  const file = await unified()
+    .use(remarkParse)
+    .use(remarkBreaks)
+    .use(remarkRehype)
+    .use(rehypeStringify)
+    .process(await read('example.md'))
+
+  console.log(String(file))
+}
 ```
 
 Now, running `node example` yields:
@@ -82,9 +138,33 @@ The default export is `remarkBreaks`.
 
 ### `unified().use(remarkBreaks)`
 
-Plugin to add break support without needing spaces.
-This adds support for GitHub style (in issues, pull requests, comments, and
-releases) hard breaks without needing spaces before newlines.
+Support hard breaks without needing spaces or escapes (turns enters into
+`<br>`s).
+There are no options.
+
+## Syntax
+
+This plugin looks for markdown line endings (`\r`, `\n`, and `\r\n`) preceded
+by zero or more spaces and tabs.
+
+## Syntax tree
+
+This plugin adds mdast [`Break`][break] nodes from to the syntax tree.
+These are the same nodes that represent breaks with spaces or escapes.
+
+## Types
+
+This package is fully typed with [TypeScript][].
+There are no extra exported types.
+
+## 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+ and `remark` version 7+.
 
 ## Security
 
@@ -95,13 +175,17 @@ attacks.
 ## Related
 
 *   [`remark-gfm`](https://github.com/remarkjs/remark-gfm)
-    — GitHub Flavored Markdown
+    — support GFM (autolink literals, footnotes, strikethrough, tables,
+    tasklists)
 *   [`remark-github`](https://github.com/remarkjs/remark-github)
-    — Auto-link references like in GitHub issues, PRs, and comments
+    — link references to commits, issues, and users, in the same way that
+    GitHub does
+*   [`remark-directive`](https://github.com/remarkjs/remark-directive)
+    — support directives
 *   [`remark-frontmatter`](https://github.com/remarkjs/remark-frontmatter)
-    — Frontmatter (YAML, TOML, and more) support
+    — support frontmatter (YAML, TOML, and more)
 *   [`remark-math`](https://github.com/remarkjs/remark-math)
-    — Math
+    — support math
 
 ## Contribute
 
@@ -147,6 +231,8 @@ abide by its terms.
 
 [npm]: https://docs.npmjs.com/cli/install
 
+[skypack]: https://www.skypack.dev
+
 [health]: https://github.com/remarkjs/.github
 
 [contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md
@@ -159,10 +245,16 @@ abide by its terms.
 
 [author]: https://wooorm.com
 
+[unified]: https://github.com/unifiedjs/unified
+
 [remark]: https://github.com/remarkjs/remark
 
 [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
 
+[typescript]: https://www.typescriptlang.org
+
 [rehype]: https://github.com/rehypejs/rehype
 
 [hast]: https://github.com/syntax-tree/hast
+
+[break]: https://github.com/syntax-tree/mdast#break