\n\n## Usage\n\nTo use the engine, install it from NPM:\n\n```\nnpm install --save @readme/markdown\n```\n\nThen [`compile`](#compile) and [`run`](#run) your MDX:\n\n```jsx\nimport RMDX from '@readme/markdown';\n\nexport default ({ body }) =>
{RMDX.run(RMDX.compile(body))}
;\n```\n\n## API\n\n### `compile`\n\nCompiles 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.\n\n#### Parameters\n\n- **`string`** (`string`)—an MDX document\n- **`opts`** ([`CompileOpts`](#compileopts), optional)—a configuration object\n\n#### Returns\n\nA string of compiled Javascript module code.\n\n### `run`\n\n> [!CAUTION]\n> 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!\n\n#### Parameters\n\n- **`string`** (`string`)—a compiled mdx document\n- **`opts`** (`RunOpts`, optional)—configuration\n\n#### Returns\n\nAn [`RMDXModule`](#rmdxmodule) of renderable components.\n\n### `mdx`\n\nCompiles an AST to a string of MDX syntax.\n\n#### Parameters\n\n- **`tree`** (`object`)—an abstract syntax tree\n- **`opts`** ([`Options`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#options '`remark-stringify` Options type'))—`remark-stringify` configuration.\n\n#### Returns\n\nAn MDX string.\n\n### Other Methods\n\n- **`mdast`**: parse MDX syntax to MDAST.\n- **`hast`**: parse MDX syntax to HAST.\n- **`plain`**: parse MDX to a plaintext string with all Markdown syntax removed. (This _does not_ `eval` the doc.)\n- **`tags`**: get a list of tag names from the doc. (This _does not_ `eval` the doc.)\n- **`utils`**: additional defaults, helper methods, components, and so on.\n\n## Types\n\n### `CompileOpts`\n\nExtends [`CompileOptions`](https://mdxjs.com/packages/mdx/#compileoptions)\n\n##### Additional Properties\n\n- **`lazyImages`** (`boolean`, optional)—load images lazily\n- **`safeMode`** (`boolean`, optional)—extract script tags from `HTMLBlock`s\n- **`components`** (`Record`, optional)—an object of tag names to mdx.\n- **`copyButtons`** (`Boolean`, optional) — add a copy button to code blocks\n- **`hardBreaks`** (`boolean`, optional)—render every newline as a ` `. `mdxish` defaults to `true`\n\n### `RunOpts`\n\nExtends [`RunOptions`](https://mdxjs.com/packages/mdx/#runoptions)\n\n##### Additional Properties\n\n- **`components`** (`Record`, optional)—a set of custom MDX components\n- **`imports`** (`Record`, optional)—an set of modules to import globally\n- **`terms`** (`GlossaryTerm[]`, optional)\n- **`variables`** (`Variables`, optional)—an object containing [user variables](https://github.com/readmeio/variable)\n\n### `RMDXModule`\n\n##### Properties\n\n- **`default`** (`() => MDXContent`)—the MDX douments default export\n- **`toc`** (`HastHeading[]`)—a list of headings in the document\n- **`Toc`** (`() => MDCContent`)—a table of contents component\n\n## Local development and testing\n\nTo 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`!\n\nIf 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).\n\n### Linking Changes to the Main Repo\n\nTo test local changes in the main readme app, use `npm pack` (not `npm link`) and clear the webpack cache:\n\n**In this repo, run:**\n\n```\nnpm ci && npm run build\n```\n\n**In the main app repo:**\n\nAdd to `.env`:\n\n```\nMARKDOWN_DIR={{path to local markdown repo}}\n```\n\nRun:\n\n```\nmake link-markdown && rm -rf webpack-cache && make webpack && make start\n```\n\n> **Note:** You must clear `webpack-cache` after every reinstall or the app will serve the old version.\n\n### Linking Changes to Storybook\n\n`npm link` works with the storybook app:\n\n**In this repo, run:**\n\n```\nnpm link && npm run watch\n```\n\n**In the main app repo, run:**\n\n```\nnpm link $PATH_TO_LOCAL_MARKDOWN_REPO\n```\n\n## Releases\n\n`@readmeio/mdxish` reviews the Cut release job, then:\n\n1. Actions → [Cut release](https://github.com/readmeio/markdown/actions/workflows/cut-release.yml) → **Run workflow**. That merges `next` into `main`; Release publishes to npm.\n2. Watch [Release](https://github.com/readmeio/markdown/actions/workflows/release.yml). It publishes, then fast-forwards `next` to that release. If `next` moved during publish, merge `main` into `next` by hand.\n3. After a real publish, Release notifies repos in `CONSUMER_DISPATCH_REPOS` (`package-released`). No-op if the variable is unset.\n\n\nMerge next into main by hand\n\nSame as steps 1–2 if you are not using Cut release:\n\n```\ngit switch next\ngit pull\ngit switch main\ngit pull\ngit merge --no-ff next\ngit push\n```\n\nWait until Release finishes (it syncs `main` back to `next`). If that sync fails:\n\n```\ngit pull\ngit switch next\ngit merge main\ngit push\n```\n\nRelease still notifies consumers when it actually publishes.\n\n\n","readmeFilename":"README.md"}
![\"rmdx\"](\"https://owlbertsio-resized.s3.amazonaws.com/Reading.psd.full.png\")
\n \n![\"NPM](\"https://img.shields.io/npm/v/@readme/markdown?style=for-the-badge\")
![\"MIT](\"https://img.shields.io/npm/l/@readme/markdown?style=for-the-badge\")
![\"Build](\"https://img.shields.io/github/actions/workflow/status/readmeio/markdown/ci.yml?branch=main&style=for-the-badge\")
![](\"https://raw.githubusercontent.com/readmeio/.github/main/oss-badge.svg\"){kind=icon}
\n