Add improved docs

Author: wooorm

lib/index.js

@@ -22,8 +22,8 @@ footnoteReference.peek = footnoteReferencePeek
 // utilities on `state`.
 
 /**
- * Create an extension for `mdast-util-from-markdown` to enable footnotes
- * in markdown like in GFM.
+ * Create an extension for `mdast-util-from-markdown` to enable GFM footnotes
+ * in markdown.
  *
  * @returns {FromMarkdownExtension}
  *   Extension for `mdast-util-from-markdown`.
@@ -46,8 +46,8 @@ export function gfmFootnoteFromMarkdown() {
 }
 
 /**
- * Create an extension for `mdast-util-to-markdown` to enable footnotes
- * in markdown like in GFM.
+ * Create an extension for `mdast-util-to-markdown` to enable GFM footnotes
+ * in markdown.
  *
  * @returns {ToMarkdownExtension}
  *   Extension for `mdast-util-to-markdown`.

readme.md

@@ -19,6 +19,8 @@
 *   [API](#api)
     *   [`gfmFootnoteFromMarkdown()`](#gfmfootnotefrommarkdown)
     *   [`gfmFootnoteToMarkdown()`](#gfmfootnotetomarkdown)
+*   [HTML](#html)
+*   [Syntax](#syntax)
 *   [Syntax tree](#syntax-tree)
     *   [Nodes](#nodes)
     *   [Content model](#content-model)
@@ -30,24 +32,35 @@
 
 ## What is this?
 
-This package contains extensions that add support for the footnote 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 footnote syntax
+in markdown to [mdast][].
+These extensions plug into
+[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
+footnotes in markdown into a syntax tree) and
+[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
+footnotes in syntax trees to markdown).
 
 GFM footnotes were [announced September 30, 2021][post] but are not specified.
 Their implementation on github.com is currently buggy.
 The bugs have been reported on [`cmark-gfm`][cmark-gfm].
 
 ## 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-footnote`][micromark-extension-gfm-footnote].
+
+When you don’t need a syntax tree, you can use [`micromark`][micromark]
+directly with `micromark-extension-gfm-footnote`.
 
 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-footnote`][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].
@@ -56,7 +69,7 @@ If your content is not in English, 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-footnote
@@ -142,19 +155,42 @@ Hi\![^1]
 
 ## API
 
-This package exports the identifiers `gfmFootnoteFromMarkdown` and
-`gfmFootnoteToMarkdown`.
+This package exports the identifiers
+[`gfmFootnoteFromMarkdown`][api-gfmfootnotefrommarkdown] and
+[`gfmFootnoteToMarkdown`][api-gfmfootnotetomarkdown].
 There is no default export.
 
 ### `gfmFootnoteFromMarkdown()`
 
-Function that can be called to get an extension for
-[`mdast-util-from-markdown`][mdast-util-from-markdown].
+Create an extension for
+[`mdast-util-from-markdown`][mdast-util-from-markdown]
+to enable GFM footnotes in markdown.
+
+###### Returns
+
+Extension for `mdast-util-from-markdown`
+([`FromMarkdownExtension`][frommarkdownextension]).
 
 ### `gfmFootnoteToMarkdown()`
 
-Function that can be called to get an extension for
-[`mdast-util-to-markdown`][mdast-util-to-markdown].
+Create an extension for
+[`mdast-util-to-markdown`][mdast-util-to-markdown]
+to enable GFM footnotes in markdown.
+
+###### Returns
+
+Extension for `mdast-util-to-markdown`
+([`ToMarkdownExtension`][tomarkdownextension]).
+
+## 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 your content is not in English, you should configure that utility.
+
+## Syntax
+
+See [Syntax in `micromark-extension-frontmatter`][syntax].
 
 ## Syntax tree
 
@@ -166,25 +202,25 @@ The following interfaces are added to **[mdast][]** by this utility.
 
 ```idl
 interface FootnoteDefinition <: Parent {
-  type: "footnoteDefinition"
+  type: 'footnoteDefinition'
   children: [FlowContent]
 }
 
 FootnoteDefinition includes Association
 ```
 
-**FootnoteDefinition** ([**Parent**][dfn-parent]) represents content relating
+**FootnoteDefinition** (**[Parent][dfn-parent]**) represents content relating
 to the document that is outside its flow.
 
-**FootnoteDefinition** can be used where [**flow**][dfn-flow-content] content is
-expected.
-Its content model is also [**flow**][dfn-flow-content] content.
+**FootnoteDefinition** can be used where **[flow][dfn-flow-content]** content
+is expected.
+Its content model is also **[flow][dfn-flow-content]** content.
 
 **FootnoteDefinition** includes the mixin
-[**Association**][dfn-mxn-association].
+**[Association][dfn-mxn-association]**.
 
 **FootnoteDefinition** should be associated with
-[**FootnoteReferences**][dfn-footnote-reference].
+**[FootnoteReferences][dfn-footnote-reference]**.
 
 For example, the following markdown:
 
@@ -210,23 +246,23 @@ Yields:
 
 ```idl
 interface FootnoteReference <: Node {
-  type: "footnoteReference"
+  type: 'footnoteReference'
 }
 
 FootnoteReference includes Association
 ```
 
-**FootnoteReference** ([**Node**][dfn-node]) represents a marker through
+**FootnoteReference** (**[Node][dfn-node]**) represents a marker through
 association.
 
 **FootnoteReference** can be used where
-[**static phrasing**][dfn-static-phrasing-content] content is expected.
+**[static phrasing][dfn-static-phrasing-content]** content is expected.
 It has no content model.
 
-**FootnoteReference** includes the mixin [**Association**][dfn-mxn-association].
+**FootnoteReference** includes the mixin **[Association][dfn-mxn-association]**.
 
 **FootnoteReference** should be associated with a
-[**FootnoteDefinition**][dfn-footnote-definition].
+**[FootnoteDefinition][dfn-footnote-definition]**.
 
 For example, the following markdown:
 
@@ -255,36 +291,35 @@ type FlowContentGfm = FootnoteDefinition | FlowContent
 #### `StaticPhrasingContent` (GFM footnotes)
 
 ```idl
-type StaticPhrasingContentGfm =
-  FootnoteReference | StaticPhrasingContent
+type StaticPhrasingContentGfm = FootnoteReference | StaticPhrasingContent
 ```
 
 ## Types
 
 This package is fully typed with [TypeScript][].
 It does not export additional types.
 
-The `FootnoteDefinition` and `FootnoteReference` node types are supported in
-`@types/mdast` by default.
+The `FootnoteDefinition` and `FootnoteReference` types of the mdast nodes are
+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
 `mdast-util-to-markdown` version 1+.
 
 ## Related
 
-*   [`remarkjs/remark-gfm`][remark-gfm]
+*   [`remark-gfm`][remark-gfm]
     — remark plugin to support GFM
-*   [`syntax-tree/mdast-util-gfm`][mdast-util-gfm]
+*   [`mdast-util-gfm`][mdast-util-gfm]
     — same but all of GFM (autolink literals, footnotes, strikethrough, tables,
     tasklists)
-*   [`micromark/micromark-extension-gfm-footnote`][extension]
+*   [`micromark-extension-gfm-footnote`][micromark-extension-gfm-footnote]
     — micromark extension to parse GFM footnotes
 
 ## Contribute
@@ -355,7 +390,11 @@ abide by its terms.
 
 [remark-gfm]: https://github.com/remarkjs/remark-gfm
 
-[extension]: https://github.com/micromark/micromark-extension-gfm-footnote
+[micromark]: https://github.com/micromark/micromark
+
+[micromark-extension-gfm-footnote]: https://github.com/micromark/micromark-extension-gfm-footnote
+
+[syntax]: https://github.com/micromark/micromark-extension-gfm-footnote#syntax
 
 [gfm]: https://github.github.com/gfm/
 
@@ -375,10 +414,18 @@ abide by its terms.
 
 [dfn-node]: https://github.com/syntax-tree/unist#node
 
+[frommarkdownextension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension
+
+[tomarkdownextension]: https://github.com/syntax-tree/mdast-util-to-markdown#options
+
 [dfn-flow-content]: #flowcontent-gfm-footnotes
 
 [dfn-static-phrasing-content]: #staticphrasingcontent-gfm-footnotes
 
 [dfn-footnote-reference]: #footnotereference
 
 [dfn-footnote-definition]: #footnotedefinition
+
+[api-gfmfootnotefrommarkdown]: #gfmfootnotefrommarkdown
+
+[api-gfmfootnotetomarkdown]: #gfmfootnotetomarkdown