Add improved docs

Author: wooorm

readme.md

@@ -8,7 +8,7 @@
 [![Backers][backers-badge]][collective]
 [![Chat][chat-badge]][chat]
 
-[mdast][] extensions to parse and serialize [MDX][] expressions.
+[mdast][] extensions to parse and serialize [MDX][] expressions (`{Math.PI}`).
 
 ## Contents
 
@@ -19,6 +19,12 @@
 *   [API](#api)
     *   [`mdxExpressionFromMarkdown`](#mdxexpressionfrommarkdown)
     *   [`mdxExpressionToMarkdown`](#mdxexpressiontomarkdown)
+    *   [`MdxFlowExpression`](#mdxflowexpression)
+    *   [`MdxTextExpression`](#mdxtextexpression)
+    *   [`MdxFlowExpressionHast`](#mdxflowexpressionhast)
+    *   [`MdxTextExpressionHast`](#mdxtextexpressionhast)
+*   [HTML](#html)
+*   [Syntax](#syntax)
 *   [Syntax tree](#syntax-tree)
     *   [Nodes](#nodes)
     *   [Content model](#content-model)
@@ -30,25 +36,33 @@
 
 ## What is this?
 
-This package contains extensions that add support for the expression syntax
-enabled by MDX 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 MDX expression syntax
+in markdown to [mdast][].
+These extensions plug into
+[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
+expressions in markdown into a syntax tree) and
+[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
+expressions 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-mdx`][remark-mdx] 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-mdx-expression`][extension].
 
 When you are working with syntax trees and want all of MDX, use
 [`mdast-util-mdx`][mdast-util-mdx] instead.
 
-When working with `mdast-util-from-markdown`, you must combine this package with
-[`micromark-extension-mdx-expression`][extension].
+All these packages are used in [`remark-mdx`][remark-mdx], which
+focusses on making it easier to transform content by abstracting these
+internals away.
 
 ## 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-mdx-expression
@@ -168,36 +182,117 @@ b {true}.
 
 ## API
 
-This package exports the identifiers `mdxExpressionFromMarkdown` and
-`mdxExpressionToMarkdown`.
+This package exports the identifiers
+[`mdxExpressionFromMarkdown`][api-mdx-expression-from-markdown] and
+[`mdxExpressionToMarkdown`][api-mdx-expression-to-markdown].
 There is no default export.
 
 ### `mdxExpressionFromMarkdown`
 
-Extension for [`mdast-util-from-markdown`][mdast-util-from-markdown].
+Extension for [`mdast-util-from-markdown`][mdast-util-from-markdown] to enable
+MDX expressions.
 
-When using the [syntax extension with `addResult`][extension], nodes will have
-a `data.estree` field set to an [ESTree][].
+When using the [micromark syntax extension][extension] with `addResult`, nodes
+will have a `data.estree` field set to an ESTree [`Program`][program] node.
 
 ### `mdxExpressionToMarkdown`
 
-Extension for [`mdast-util-to-markdown`][mdast-util-to-markdown].
+Extension for [`mdast-util-to-markdown`][mdast-util-to-markdown] to enable MDX
+expressions.
+
+### `MdxFlowExpression`
+
+MDX expression node, occurring in flow (block) (TypeScript type).
+
+###### Type
+
+```ts
+import type {Program} from 'estree-jsx'
+import type {Literal} from 'mdast'
+
+interface MdxFlowExpression extends Literal {
+  type: 'mdxFlowExpression'
+  data?: {estree?: Program | null | undefined} & Literal['data']
+}
+```
+
+### `MdxTextExpression`
+
+MDX expression node, occurring in text (block) (TypeScript type).
+
+###### Type
+
+```ts
+import type {Program} from 'estree-jsx'
+import type {Literal} from 'mdast'
+
+interface MdxTextExpression extends Literal {
+  type: 'mdxTextExpression'
+  data?: {estree?: Program | null | undefined} & Literal['data']
+}
+```
+
+### `MdxFlowExpressionHast`
+
+Same as [`MdxFlowExpression`][api-mdx-flow-expression], but registered with
+`@types/hast` (TypeScript type).
+
+###### Type
+
+```ts
+import type {Program} from 'estree-jsx'
+import type {Literal} from 'hast'
+
+interface MdxFlowExpressionHast extends Literal {
+  type: 'mdxFlowExpression'
+  data?: {estree?: Program | null | undefined} & Literal['data']
+}
+```
+
+### `MdxTextExpressionHast`
+
+Same as [`MdxTextExpression`][api-mdx-text-expression], but registered with
+`@types/hast` (TypeScript type).
+
+###### Type
+
+```ts
+import type {Program} from 'estree-jsx'
+import type {Literal} from 'hast'
+
+interface MdxTextExpressionHast extends Literal {
+  type: 'mdxTextExpression'
+  data?: {estree?: Program | null | undefined} & Literal['data']
+}
+```
+
+## HTML
+
+MDX expressions have no representation in HTML.
+Though, when you are dealing with MDX, you will likely go *through* hast.
+You can enable passing MDX expressions through to hast by configuring
+[`mdast-util-to-hast`][mdast-util-to-hast] with
+`passThrough: ['mdxFlowExpression', 'mdxTextExpression']`.
+
+## Syntax
+
+See [Syntax in `micromark-extension-mdx-expression`][syntax].
 
 ## Syntax tree
 
 The following interfaces are added to **[mdast][]** by this utility.
 
 ### Nodes
 
-#### `MDXFlowExpression`
+#### `MdxFlowExpression`
 
 ```idl
-interface MDXFlowExpression <: Literal {
+interface MdxFlowExpression <: Literal {
   type: "mdxFlowExpression"
 }
 ```
 
-**MDXFlowExpression** (**[Literal][dfn-literal]**) represents a JavaScript
+**MdxFlowExpression** (**[Literal][dfn-literal]**) represents a JavaScript
 expression embedded in flow (block).
 It can be used where **[flow][dfn-flow-content]** content is expected.
 Its content is represented by its `value` field.
@@ -216,15 +311,15 @@ Yields:
 {type: 'mdxFlowExpression', value: '\n1 + 1\n'}
 ```
 
-#### `MDXTextExpression`
+#### `MdxTextExpression`
 
 ```idl
-interface MDXTextExpression <: Literal {
+interface MdxTextExpression <: Literal {
   type: "mdxTextExpression"
 }
 ```
 
-**MDXTextExpression** (**[Literal][dfn-literal]**) represents a JavaScript
+**MdxTextExpression** (**[Literal][dfn-literal]**) represents a JavaScript
 expression embedded in text (span, inline).
 It can be used where **[phrasing][dfn-phrasing-content]** content is expected.
 Its content is represented by its `value` field.
@@ -246,21 +341,24 @@ Yields:
 #### `FlowContent` (MDX expression)
 
 ```idl
-type FlowContentMdxExpression = MDXFlowExpression | FlowContent
+type FlowContentMdxExpression = MdxFlowExpression | FlowContent
 ```
 
 #### `PhrasingContent` (MDX expression)
 
 ```idl
-type PhrasingContentMdxExpression = MDXTextExpression | PhrasingContent
+type PhrasingContentMdxExpression = MdxTextExpression | PhrasingContent
 ```
 
 ## Types
 
 This package is fully typed with [TypeScript][].
-It exports the additional types `MdxFlowExpression` and `MdxTextExpression`.
+It exports the additional types [`MdxFlowExpression`][api-mdx-flow-expression],
+[`MdxFlowExpressionHast`][api-mdx-flow-expression-hast],
+[`MdxTextExpression`][api-mdx-text-expression], and
+[`MdxTextExpressionHast`][api-mdx-text-expression-hast].
 
-It also registers the node types with `@types/mdast`.
+It also registers the node types with `@types/mdast` and `@types/hast`.
 If you’re working with the syntax tree, make sure to import this utility
 somewhere in your types, as that registers the new node types in the tree.
 
@@ -283,7 +381,7 @@ visit(tree, (node) => {
 
 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
@@ -362,6 +460,8 @@ abide by its terms.
 
 [mdast]: https://github.com/syntax-tree/mdast
 
+[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast
+
 [mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
 
 [mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
@@ -370,14 +470,28 @@ abide by its terms.
 
 [extension]: https://github.com/micromark/micromark-extension-mdx-expression
 
-[estree]: https://github.com/estree/estree
+[syntax]: https://github.com/micromark/micromark-extension-mdx-expression#syntax
 
-[dfn-literal]: https://github.com/syntax-tree/mdast#literal
-
-[dfn-flow-content]: #flowcontent-mdx-expression
+[program]: https://github.com/estree/estree/blob/master/es2015.md#programs
 
-[dfn-phrasing-content]: #phrasingcontent-mdx-expression
+[dfn-literal]: https://github.com/syntax-tree/mdast#literal
 
 [remark-mdx]: https://mdxjs.com/packages/remark-mdx/
 
 [mdx]: https://mdxjs.com
+
+[api-mdx-expression-from-markdown]: #mdxexpressionfrommarkdown
+
+[api-mdx-expression-to-markdown]: #mdxexpressiontomarkdown
+
+[api-mdx-flow-expression]: #mdxflowexpression
+
+[api-mdx-text-expression]: #mdxtextexpression
+
+[api-mdx-flow-expression-hast]: #mdxflowexpressionhast
+
+[api-mdx-text-expression-hast]: #mdxtextexpressionhast
+
+[dfn-flow-content]: #flowcontent-mdx-expression
+
+[dfn-phrasing-content]: #phrasingcontent-mdx-expression