Add improved docs

Author: wooorm

readme.md

@@ -19,6 +19,8 @@
 *   [API](#api)
     *   [`gfmStrikethroughFromMarkdown`](#gfmstrikethroughfrommarkdown)
     *   [`gfmStrikethroughToMarkdown`](#gfmstrikethroughtomarkdown)
+*   [HTML](#html)
+*   [Syntax](#syntax)
 *   [Syntax tree](#syntax-tree)
     *   [Nodes](#nodes)
     *   [Content model](#content-model)
@@ -30,20 +32,31 @@
 
 ## What is this?
 
-This package contains extensions that add support for the strikethrough syntax
-enabled by GFM to [`mdast-util-from-markdown`][mdast-util-from-markdown] and
-[`mdast-util-to-markdown`][mdast-util-to-markdown].
+This package contains two extensions that add support for GFM strikethrough
+syntax in markdown to [mdast][].
+These extensions plug into
+[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
+strikethrough in markdown into a syntax tree) and
+[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
+strikethrough in syntax trees to markdown).
 
 ## When to use this
 
-These tools are all rather low-level.
-In most cases, you’d want to use [`remark-gfm`][remark-gfm] with remark instead.
+You can use these extensions when you are working with
+`mdast-util-from-markdown` and `mdast-util-to-markdown` already.
+
+When working with `mdast-util-from-markdown`, you must combine this package
+with [`micromark-extension-gfm-strikethrough`][extension].
+
+When you don’t need a syntax tree, you can use [`micromark`][micromark]
+directly with `micromark-extension-gfm-strikethrough`.
 
 When you are working with syntax trees and want all of GFM, use
 [`mdast-util-gfm`][mdast-util-gfm] instead.
 
-When working with `mdast-util-from-markdown`, you must combine this package with
-[`micromark-extension-gfm-strikethrough`][extension].
+All these packages are used [`remark-gfm`][remark-gfm], which
+focusses on making it easier to transform content by abstracting these
+internals away.
 
 This utility does not handle how markdown is turned to HTML.
 That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].
@@ -52,7 +65,7 @@ If you want a different element, you should configure that utility.
 ## Install
 
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+In Node.js (version 14.14+ and 16.0+), install with [npm][]:
 
 ```sh
 npm install mdast-util-gfm-strikethrough
@@ -130,17 +143,30 @@ Now, running `node example` yields:
 
 ## API
 
-This package exports the identifiers `gfmStrikethroughFromMarkdown` and
-`gfmStrikethroughToMarkdown`.
+This package exports the identifiers
+[`gfmStrikethroughFromMarkdown`][api-gfm-strikethrough-from-markdown] and
+[`gfmStrikethroughToMarkdown`][api-gfm-strikethrough-to-markdown].
 There is no default export.
 
 ### `gfmStrikethroughFromMarkdown`
 
-Extension for [`mdast-util-from-markdown`][mdast-util-from-markdown].
+Extension for [`mdast-util-from-markdown`][mdast-util-from-markdown] to enable
+GFM strikethrough ([`FromMarkdownExtension`][from-markdown-extension]).
 
 ### `gfmStrikethroughToMarkdown`
 
-Extension for [`mdast-util-to-markdown`][mdast-util-to-markdown].
+Extension for [`mdast-util-to-markdown`][mdast-util-to-markdown] to enable
+GFM strikethrough ([`ToMarkdownExtension`][to-markdown-extension]).
+
+## HTML
+
+This utility does not handle how markdown is turned to HTML.
+That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].
+If you want a different element, you should configure that utility.
+
+## Syntax
+
+See [Syntax in `micromark-extension-gfm-strikethrough`][syntax].
 
 ## Syntax tree
 
@@ -152,17 +178,17 @@ The following interfaces are added to **[mdast][]** by this utility.
 
 ```idl
 interface Delete <: Parent {
-  type: "delete"
+  type: 'delete'
   children: [TransparentContent]
 }
 ```
 
-**Delete** ([**Parent**][dfn-parent]) represents contents that are no longer
+**Delete** (**[Parent][dfn-parent]**) represents contents that are no longer
 accurate or no longer relevant.
 
-**Delete** can be used where [**static phrasing**][dfn-static-phrasing-content]
+**Delete** can be used where **[static phrasing][dfn-static-phrasing-content]**
 content is expected.
-Its content model is [**transparent**][dfn-transparent-content] content.
+Its content model is **[transparent][dfn-transparent-content]** content.
 
 For example, the following markdown:
 
@@ -192,13 +218,13 @@ type StaticPhrasingContentGfm = Delete | StaticPhrasingContent
 This package is fully typed with [TypeScript][].
 It does not export additional types.
 
-The `Delete` node type is supported in `@types/mdast` by default.
+The `Delete` type of the mdast node is exposed from `@types/mdast`.
 
 ## 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+.
+As of now, that is Node.js 14.14+ and 16.0+.
 Our projects sometimes work with older versions, but this is not guaranteed.
 
 This plugin works with `mdast-util-from-markdown` version 1+ and
@@ -286,14 +312,26 @@ abide by its terms.
 
 [mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
 
+[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension
+
 [mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
 
+[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options
+
 [mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm
 
 [mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast
 
+[micromark]: https://github.com/micromark/micromark
+
 [extension]: https://github.com/micromark/micromark-extension-gfm-strikethrough
 
+[syntax]: https://github.com/micromark/micromark-extension-gfm-strikethrough#syntax
+
 [dfn-parent]: https://github.com/syntax-tree/mdast#parent
 
 [dfn-static-phrasing-content]: #staticphrasingcontent-gfm-strikethrough
+
+[api-gfm-strikethrough-from-markdown]: #gfmstrikethroughfrommarkdown
+
+[api-gfm-strikethrough-to-markdown]: #gfmstrikethroughtomarkdown