Add improved docs

Author: wooorm

readme.md

@@ -8,38 +8,82 @@
 [![Backers][backers-badge]][collective]
 [![Chat][chat-badge]][chat]
 
-**[micromark][]** extension to support MDX (agnostic to JS).
-Use [`micromark-extension-mdxjs`][mdxjs] instead to support MDX.js.
-
-This package provides the low-level modules for integrating with the micromark
-tokenizer but has no handling of compiling to HTML: go to a syntax tree instead.
+[micromark][] extensions to support [MDX][mdxjs], unaware of JavaScript.
+
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When to use this](#when-to-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`mdx()`](#mdx)
+*   [Authoring](#authoring)
+*   [Syntax](#syntax)
+*   [Errors](#errors)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
+
+This package contains an extension that adds support for the syntax enabled
+by [MDX][mdxjs] to [`micromark`][micromark].
+This extension is used inside MDX.
+It supports expressions, JSX, and turns some markdown features off.
+It is not aware of the syntax of JavaScript inside expressions and does not
+support export/imports.
 
 ## When to use this
 
-You should probably use [`micromark-extension-mdxjs`][mdxjs] instead, which
-supports JavaScript.
-Alternatively, if you don’t want JavaScript-aware parsing, use this package.
+You can use this extension when you are working with [`micromark`][micromark].
 
-If you don’t need all of MDX, the extensions can be used separately:
+This project is useful when you want to support MDX, unaware of JavaScript, for
+example because expressions can include Rust or variables or whatnot.
+If you want to be aware of JavaScript, use
+[`micromark-extension-mdxjs`][micromark-extension-mdxjs].
 
-*   [`micromark/micromark-extension-mdx-expression`][mdx-expression]
-    — support MDX (or MDX.js) expressions
-*   [`micromark/micromark-extension-mdx-jsx`][mdx-jsx]
-    — support MDX (or MDX.js) JSX
-*   [`micromark/micromark-extension-mdx-md`][mdx-md]
-    — turn some markdown features off for MDX (or MDX.js)
+Alternatively, you can also use the underlying syntax extensions separately:
 
-## Install
+*   [`micromark-extension-mdx-expression`][micromark-extension-mdx-expression]
+    — support MDX expressions
+*   [`micromark-extension-mdx-jsx`][micromark-extension-mdx-jsx]
+    — support MDX JSX
+*   [`micromark-extension-mdx-md`][micromark-extension-mdx-md]
+    — turn some CommonMark features off
+
+When you need a syntax tree, combine this package with
+[`mdast-util-mdx`][mdast-util-mdx].
 
-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.
+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
 
-[npm][]:
+This package is [ESM only][esm].
+In Node.js (version 16+), install with [npm][]:
 
 ```sh
 npm install micromark-extension-mdx
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {mdx} from 'https://esm.sh/micromark-extension-mdx@1'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {mdx} from 'https://esm.sh/micromark-extension-mdx@1?bundle'
+</script>
+```
+
 ## Use
 
 ```js
@@ -57,35 +101,78 @@ Yields:
 <p>a  c  d</p>
 ```
 
-…which is rather useless: go to a syntax tree with
-[`mdast-util-from-markdown`][from-markdown] and
+…which is useless: go to a syntax tree with
+[`mdast-util-from-markdown`][mdast-util-from-markdown] and
 [`mdast-util-mdx`][mdast-util-mdx] instead.
 
 ## API
 
-This package exports the following identifiers: `mdx`.
+This package exports the identifier [`mdx`][api-mdx].
 There is no default export.
 
+The separate extensions support the [`development` condition][development].
+Run `node --conditions development module.js` to get instrumented dev code.
+Without this condition, production code is loaded.
+
 ### `mdx()`
 
-A function that can be called which returns an extension for micromark to parse
-MDX (can be passed in `extensions`).
-There are no options yet.
+Create an extension for `micromark` to enable MDX syntax, unaware of JavaScript.
+
+###### Returns
+
+Extension for `micromark` that can be passed in `extensions` to enable MDX
+syntax, unaware of JavaScript ([`Extension`][micromark-extension]).
+
+## Authoring
+
+For recommendations on how to author MDX, see each corresponding readme:
+
+*   [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#authoring)
+*   [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#authoring)
+*   [CommonMark features not in MDX](https://github.com/micromark/micromark-extension-mdx-md#authoring)
+
+## Syntax
+
+For info on the syntax of these features, see each corresponding readme:
+
+*   [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#syntax)
+*   [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#syntax)
+*   CommonMark features not in MDX: n/a
+
+## Errors
+
+For info on what errors are thrown, see each corresponding readme:
+
+*   [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#errors)
+*   [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#errors)
+*   CommonMark features not in MDX: n/a
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports no additional types.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with all maintained
+versions of Node.js.
+As of now, that is Node.js 16+.
+Our projects sometimes work with older versions, but this is not guaranteed.
+
+These extensions work with `micromark` version 3+.
+
+## Security
+
+This package is safe.
 
 ## Related
 
-*   [`micromark/micromark`][micromark]
-    — the smallest commonmark-compliant markdown parser that exists
-*   [`micromark/micromark-extension-mdxjs`][mdxjs]
-    — micromark extension to support MDX.js
-*   [`micromark/micromark-extension-mdx-expression`][mdx-expression]
-    — micromark extension to support MDX (or MDX.js) expressions
-*   [`micromark/micromark-extension-mdx-jsx`][mdx-jsx]
-    — micromark extension to support MDX (or MDX.js) JSX
-*   [`micromark/micromark-extension-mdx-md`][mdx-md]
-    — micromark extension to support misc MDX changes
-*   [`syntax-tree/mdast-util-mdx`][mdast-util-mdx]
-    — mdast utility to support MDX (or MDX.js)
+*   [`micromark-extension-mdxjs`][micromark-extension-mdxjs]
+    — support MDX aware of JS
+*   [`mdast-util-mdx`][mdast-util-mdx]
+    — support MDX in mdast
+*   [`remark-mdx`][remark-mdx]
+    — support MDX syntax in remark
 
 ## Contribute
 
@@ -131,26 +218,42 @@ abide by its terms.
 
 [npm]: https://docs.npmjs.com/cli/install
 
+[esmsh]: https://esm.sh
+
 [license]: license
 
 [author]: https://wooorm.com
 
-[contributing]: https://github.com/micromark/.github/blob/HEAD/contributing.md
+[contributing]: https://github.com/micromark/.github/blob/main/contributing.md
+
+[support]: https://github.com/micromark/.github/blob/main/support.md
+
+[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md
 
-[support]: https://github.com/micromark/.github/blob/HEAD/support.md
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
 
-[coc]: https://github.com/micromark/.github/blob/HEAD/code-of-conduct.md
+[typescript]: https://www.typescriptlang.org
+
+[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions
 
 [micromark]: https://github.com/micromark/micromark
 
-[mdxjs]: https://github.com/micromark/micromark-extension-mdxjs
+[micromark-extension]: https://github.com/micromark/micromark#syntaxextension
+
+[micromark-extension-mdxjs]: https://github.com/micromark/micromark-extension-mdxjs
+
+[micromark-extension-mdx-expression]: https://github.com/micromark/micromark-extension-mdx-expression
 
-[mdx-expression]: https://github.com/micromark/micromark-extension-mdx-expression
+[micromark-extension-mdx-jsx]: https://github.com/micromark/micromark-extension-mdx-jsx
 
-[mdx-jsx]: https://github.com/micromark/micromark-extension-mdx-jsx
+[micromark-extension-mdx-md]: https://github.com/micromark/micromark-extension-mdx-md
 
-[mdx-md]: https://github.com/micromark/micromark-extension-mdx-md
+[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
 
 [mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx
 
-[from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
+[remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[mdxjs]: https://mdxjs.com
+
+[api-mdx]: #mdx