Add better docs

example.js

@@ -0,0 +1,6 @@
+import {micromark} from 'micromark'
+import {mdx} from './index.js'
+
+const output = micromark('a <b /> c {1 + 1} d', {extensions: [mdx()]})
+
+console.log(output)

readme.md

@@ -14,11 +14,13 @@ 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.
 
-You probably should use this package with [`mdast-util-mdx`][mdast-util-mdx]
-(**[mdast][]**) or alternatively use both through [`remark-mdx`][remark-mdx]
-(**[remark][]**).
+## When to use this
 
-The extensions can be used separately:
+You should probably use [`micromark-extension-mdxjs`][mdxjs] instead, which
+supports JavaScript.
+Alternatively, if you don’t want JavaScript-aware parsing, use this package.
+
+If you don’t need all of MDX, the extensions can be used separately:
 
 *   [`micromark/micromark-extension-mdx-expression`][mdx-expression]
     — support MDX (or MDX.js) expressions
@@ -40,7 +42,24 @@ npm install micromark-extension-mdx
 
 ## Use
 
-See [`mdast-util-mdx`][mdast-util-mdx] for an example.
+```js
+import {micromark} from 'micromark'
+import {mdx} from 'micromark-extension-mdx'
+
+const output = micromark('a <b /> c {1 + 1} d', {extensions: [mdx()]})
+
+console.log(output)
+```
+
+Yields:
+
+```html
+<p>a  c  d</p>
+```
+
+…which is rather useless: go to a syntax tree with
+[`mdast-util-from-markdown`][from-markdown] and
+[`mdast-util-mdx`][mdast-util-mdx] instead.
 
 ## API
 
@@ -49,13 +68,10 @@ There is no default export.
 
 ### `mdx()`
 
-Support MDX (agnostic to JS).
-
+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.
 
-The export is a function that can be called to return an extension for the
-micromark parser (to tokenize MDX; can be passed in `extensions`).
-
 ## Related
 
 *   [`micromark/micromark`][micromark]
@@ -127,10 +143,6 @@ abide by its terms.
 
 [micromark]: https://github.com/micromark/micromark
 
-[remark]: https://github.com/remarkjs/remark
-
-[mdast]: https://github.com/syntax-tree/mdast
-
 [mdxjs]: https://github.com/micromark/micromark-extension-mdxjs
 
 [mdx-expression]: https://github.com/micromark/micromark-extension-mdx-expression
@@ -141,4 +153,4 @@ abide by its terms.
 
 [mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx
 
-[remark-mdx]: https://github.com/mdx-js/mdx/tree/next/packages/remark-mdx
+[from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown