docs: update readme for MDX (#957)

## 🧰 Changes

- [x] update the repo's readme for an MDX world
- [x] some minor housekeeping edits for consistency

---------

Co-authored-by: Mansa <[email protected]>

README.md

@@ -2,7 +2,7 @@
 
 <img align="right" width="26%" src="https://owlbertsio-resized.s3.amazonaws.com/Reading.psd.full.png">
 
-ReadMe's flavored Markdown parser and MDX rendering engine. <img align=center src=https://github.com/readmeio/markdown/workflows/CI/badge.svg alt="RDMD CI Status">
+ReadMe's MDX rendering engine and custom component collection. <img align=center src=https://github.com/readmeio/markdown/workflows/CI/badge.svg alt="RDMD CI Status">
 
 ```
 npm install --save @readme/markdown
@@ -21,25 +21,21 @@ export default ({ body }) => <div className="markdown-body">{run(compile(body))}
 
 #### `compile`
 
-Compiles mdx to js. A wrapper around [`mdx.compile`](https://mdxjs.com/packages/mdx/#compilefile-options)
-
-You usually only need this when calling `run` as well. It's been left as a seperate step as a potential caching opportunity.
+Compiles MDX to JS. Essentially a wrapper around [`mdx.compile`](https://mdxjs.com/packages/mdx/#compilefile-options). You usually only need this when calling `run` as well. It's been left as a seperate step as a potential caching opportunity.
 
 ###### Parameters
 
-- `string` (`string`) -- An mdx document
-- `opts` ([`CompileOpts`](#compileopts), optional) -- configuration
+- `string` (`string`) -- an MDX document
+- `opts` ([`CompileOpts`](#compileopts), optional) -- a configuration object
 
 ###### Returns
 
 compiled code (`string`)
 
 #### `run`
 
-Run compiled code. A wrapper around [`mdx.run`](https://mdxjs.com/packages/mdx/#runcode-options)
-
 > [!CAUTION]
-> This `eval`'s JavaScript.
+> **This will `eval` the compiled MDX**! Essentially a wrapper around [`mdx.run`](https://mdxjs.com/packages/mdx/#runcode-options).
 
 ###### Parameters
 
@@ -64,17 +60,11 @@ Parses mdx to an hast.
 
 #### `plain`
 
-Parses mdx to a plain string.
-
-> [!WARNING]
-> This **does** not `eval` the doc.
+Parses mdx to a plain string. (This **does** not `eval` the doc.)
 
 #### `tags`
 
-Returns a list of tag names from the doc.
-
-> [!WARNING]
-> This **does** not `eval` the doc.
+Returns a list of tag names from the doc. (This **does** not `eval` the doc.)
 
 #### `utils`
 
@@ -86,35 +76,33 @@ Extends [`CompileOptions`](https://mdxjs.com/packages/mdx/#compileoptions)
 
 ###### Additional Properties
 
-- `lazyImages` (`boolean`, optional) -- Load images lazily.
-- `safeMode` (`boolean`, optional) -- Extract script tags from `HTMLBlock`s
-- `components` (`Record<string, string>`, optional) -- An object of tag names to mdx.
-- `copyButtons` (`Boolean`, optional) — Automatically insert a button to copy a block of text to the clipboard. Currently used on `<code>` elements.
+- `lazyImages` (`boolean`, optional) -- load images lazily
+- `safeMode` (`boolean`, optional) -- extract script tags from `HTMLBlock`s
+- `components` (`Record<string, string>`, optional) -- an object of tag names to mdx.
+- `copyButtons` (`Boolean`, optional) — add a copy button to code blocks
 
 ### `RunOpts`
 
 Extends [`RunOptions`](https://mdxjs.com/packages/mdx/#runoptions)
 
 ###### Additional Properties
 
-- `components` (`Record<string, MDXModule>`, optional) -- An object of tag names to executed components.
-- `imports` (`Record<string, unknown>`, optional) -- An object of modules to import.
+- `components` (`Record<string, MDXModule>`, optional) -- a set of custom MDX components
+- `imports` (`Record<string, unknown>`, optional) -- an set of modules to import globally
 - `terms` (`GlossaryTerm[]`, optional)
-- `variables` (`Variables`, optional) -- An object containing [user variables}(https://github.com/readmeio/variable).
+- `variables` (`Variables`, optional) -- an object containing [user variables](https://github.com/readmeio/variable)
 
 ### `RMDXModule`
 
 ###### Properties
 
-- `default` (`() => MDXContent`) -- The mdx douments default export
-- `toc` (`HastHeading[]`) -- A list of headings in the document
-- `Toc` (`() => MDCContent`) -- A table of contents component
+- `default` (`() => MDXContent`) -- the MDX douments default export
+- `toc` (`HastHeading[]`) -- a list of headings in the document
+- `Toc` (`() => MDCContent`) -- a table of contents component
 
 ## Flavored Syntax
 
-~~Our old editor rendered "Magic Block" components from a custom, JSON-based syntax. To provide seamless backwards-compatibility, our new processor ships with built in support for parsing this old format, and transpiles it straight in to our new, flavored Markdown.~~
-
-We've also sprinkled a bit of our own syntactic sugar on top to let you supercharge your docs. [**Learn more about ReadMe's flavored syntax!**](https://docs.readme.com/rdmd/docs/syntax-extensions)
+We've also sprinkled a bit of our own custom components in to help you supercharge your docs. [**Learn more about ReadMe's new MDX engine!**](https://docs.readme.com/rdmd/page/mdx-engine)
 
 ## Local Development
 
@@ -131,8 +119,3 @@ If you make changes to the docs or how the markdown is rendered, you may need to
 ```
 make updateSnapshot
 ```
-
-## Credits
-
-- **License**: MIT
-- **Authors**: [Dom Harrington](https://github.com/domharrington/), [Rafe Goldberg](https://github.com/rafegoldberg)