@readme/markdown

ReadMe's MDX rendering engine and custom component collection.


_{Use ReadMe? Learn more about our upcoming move to MDX!}

Usage

To use the engine, install it from NPM:

``
npm install --save @readme/markdown
`

Then compile and run your MDX:

`jsx
import RMDX from '@readme/markdown';

export default ({ body }) =>

;
`

API

$3

Compiles MDX to JS. Essentially a wrapper around mdx.compile. Used before calling run; it has been left as a seperate method for potential caching opportunities.

#### Parameters

- string (string)—an MDX document
- opts (CompileOpts, optional)—a configuration object

#### Returns

A string of compiled Javascript module code.

$3

> [!CAUTION]
> This is essentially a wrapper around mdx.run 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 of renderable components.

$3

Compiles an AST to a string of MDX syntax.

#### Parameters

- tree (object)—an abstract syntax tree
- opts ( Options type'" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">Options)—remark-stringify configuration.

#### Returns

An MDX string.

$3

- 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.

Types

$3

Extends CompileOptions

##### Additional Properties

- lazyImages (boolean, optional)—load images lazily
- safeMode (boolean, optional)—extract script tags from HTMLBlocks
- components (Record, optional)—an object of tag names to mdx.
- copyButtons (Boolean, optional) — add a copy button to code blocks

$3

Extends RunOptions

##### 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

$3

##### Properties

- default (() => MDXContent)—the MDX douments default export
- toc (HastHeading[])—a list of headings in the document
- Toc (() => MDCContent)—a table of contents component

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!

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. You may want to increase the memory usage. If you have not already, you'll need to create an account for docker hub and sign-in locally.

$3

There's currently some babel issues that prevent npm linking to our main repo. npm linking does work with our storybook app.

In this repo, run:

`
npm link && npm run watch
`

In the main app repo, run:

`
npm link $PATH_TO_LOCAL_MARKDOWN_REPO
`

Releases

First, update main with what’s on next:

`
git switch next
git pull
git switch main
git pull
git merge --no-ff next
git push
`

WAIT until the build is finished, then update next:

`
git pull
git switch next
git merge main
git push
``