readmeio · rafegoldberg · Oct 11, 2024 · Oct 11, 2024
diff --git a/README.md b/README.md
@@ -1,129 +1,110 @@
-# @readme/markdown
+# <img align="right" width="26%" src="https://owlbertsio-resized.s3.amazonaws.com/Reading.psd.full.png"> `@readme/markdown`
 
-<img align="right" width="26%" src="https://owlbertsio-resized.s3.amazonaws.com/Reading.psd.full.png">
+<img align=right src=https://github.com/readmeio/markdown/workflows/CI/badge.svg alt="RDMD CI Status"> ReadMe's MDX rendering engine and custom component collection.
+<br/>  *(Use ReadMe? [Learn more about our upcoming move to MDX](https://docs.readme.com/rdmd/page/mdx-engine)!)*
 
-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">
+## Getting Started
+
+To use the engine, install it from NPM:
 
 ```
 npm install --save @readme/markdown
 ```
 
-## Usage
+Then [`compile`](#compile) and [`run`](#run) your MDX:
 
 ```jsx
-import React from 'react';
-import rmdx from '@readme/markdown';
+import RMDX from '@readme/markdown';
 
-export default ({ body }) => <div className="markdown-body">{run(compile(body))}</div>;
+export default ({ body }) => (
+  <div className="markdown-body">
+    {RMDX.run(RMDX.compile(body))}
+  </div>
+);
 ```
 
-### API
+## API
 
-#### `compile`
+### `compile`
 
-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.
+Compiles MDX to JS. Essentially a wrapper around [`mdx.compile`](https://mdxjs.com/packages/mdx/#compilefile-options). Used before calling [`run`](#run); it has been left as a seperate method for potential caching opportunities.
 
-###### Parameters
+#### Parameters
 
-- `string` (`string`) -- an MDX document
-- `opts` ([`CompileOpts`](#compileopts), optional) -- a configuration object
+- **`string`** (`string`)—an MDX document
+- **`opts`** ([`CompileOpts`](#compileopts), optional)—a configuration object
 
-###### Returns
+#### Returns
 
-compiled code (`string`)
+A string of compiled Javascript module code.
 
-#### `run`
+### `run`
 
 > [!CAUTION]
-> **This will `eval` the compiled MDX**! Essentially a wrapper around [`mdx.run`](https://mdxjs.com/packages/mdx/#runcode-options).
-
-###### Parameters
-
-- `string` (`string`) -- A compiled mdx document
-- `opts` (`RunOpts`, optional) -- configuration
-
-###### Returns
-
-A module ([`RMDXModule`](#rmdxmodule)) of renderable components
-
-#### `mdx`
-
-Compiles an ast to mdx.
-
-###### Parameters
-
-Extends [`remark-stringify` options](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#options).
-
-###### Returns
+> This is essentially a wrapper around [`mdx.run`](https://mdxjs.com/packages/mdx/#runcode-options) and **it will `eval` the compiled MDX**. Make sure you only call `run` on safe syntax from a trusted author!
+>
+> #### Parameters
+> - **`string`** (`string`)—a compiled mdx document
+> - **`opts`** (`RunOpts`, optional)—configuration
+>
+> #### Returns
+> An [`RMDXModule`](#rmdxmodule) of renderable components.
 
-An mdx string.
+### `mdx`
 
-#### `mdast`
+Compiles an AST to a string of MDX syntax.
 
-Parses mdx to an mdast.
+#### Parameters
 
-#### `hast`
+- **`tree`** (`object`)—an abstract syntax tree
+- **`opts`** ([`Options`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#options "`remark-stringify` Options type"))—`remark-stringify` configuration.
 
-Parses mdx to an hast.
+#### Returns
 
-#### `plain`
+An MDX string.
 
-Parses mdx to a plain string. (This **does** not `eval` the doc.)
+### Other Methods
 
-#### `tags`
+- **`mdast`**: parse MDX syntax to MDAST.
+- **`hast`**: parse MDX syntax to HAST.
+- **`plain`**: parse MDX to a plaintext string with all Markdown syntax removed. (This *does not* `eval` the doc.)
+- **`tags`**: get a list of tag names from the doc. (This *does not* `eval` the doc.)
+- **`utils`**: additional defaults, helper methods, components, and so on.
 
-Returns a list of tag names from the doc. (This **does** not `eval` the doc.)
-
-#### `utils`
-
-Additional defaults, helpers, components, etc.
+## Types
 
 ### `CompileOpts`
 
 Extends [`CompileOptions`](https://mdxjs.com/packages/mdx/#compileoptions)
 
-###### Additional Properties
+##### 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) — add a copy button to code blocks
+- **`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
+##### Additional Properties
 
-- `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)
+- **`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)
 
 ### `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
+##### Properties
 
-## Flavored Syntax
+- **`default`** (`() => MDXContent`)—the MDX douments default export
+- **`toc`** (`HastHeading[]`)—a list of headings in the document
+- **`Toc`** (`() => MDCContent`)—a table of contents component
 
-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
+## Local Development and Testing
 
 To make changes to the RDMD engine locally, run the local development server. Clone the repo, `cd` in to it, `npm install`, and `npm run start`!
 
-### Environment setup
-
-Running the browser tests requires `docker`. Follow the docker [install instructions for mac](https://docs.docker.com/docker-for-mac/install/). You may want to increase the [memory usage](https://docs.docker.com/docker-for-mac/#resources). If you have not already, you'll need to create an account for `docker hub` and [sign-in locally](https://docs.docker.com/docker-for-mac/#docker-hub).
-
-### Running visual regression tests
-
-If you make changes to the docs or how the markdown is rendered, you may need to update the visual regression snapshots. You can run the visual regression tests in a docker container with:
-
-```
-make updateSnapshot
-```
+If you make changes to the docs or how the markdown is rendered, you may need to update the visual regression snapshots by running `make updateSnapshot`. Running these browser tests requires `docker`. Follow the docker [install instructions for mac](https://docs.docker.com/docker-for-mac/install/). You may want to increase the [memory usage](https://docs.docker.com/docker-for-mac/#resources). If you have not already, you'll need to create an account for `docker hub` and [sign-in locally](https://docs.docker.com/docker-for-mac/#docker-hub).