diff --git a/README.md b/README.md index 234612387..ab03029d7 100644 --- a/README.md +++ b/README.md @@ -1,129 +1,110 @@ -# @readme/markdown +# `@readme/markdown` - +RDMD CI Status ReadMe's MDX rendering engine and custom component collection. +
  *(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. 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 }) =>
{run(compile(body))}
; +export default ({ body }) => ( +
+ {RMDX.run(RMDX.compile(body))} +
+); ``` -### 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`, 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`, 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`, optional) -- a set of custom MDX components -- `imports` (`Record`, 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`, optional)—a set of custom MDX components +- **`imports`** (`Record`, 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).