ReadMe's MDX rendering engine and custom component collection.
npm install --save @readme/markdown
import React from 'react';
import rmdx from '@readme/markdown';
export default ({ body }) => <div className="markdown-body">{run(compile(body))}</div>;
compile
Compiles MDX to JS. Essentially a wrapper around mdx.compile
. You usually only need this when calling run
as well. It's been left as a seperate step as a potential caching opportunity.
string
(string
) -- an MDX documentopts
(CompileOpts
, optional) -- a configuration objectcompiled code (string
)
run
[!CAUTION] This will
eval
the compiled MDX! Essentially a wrapper aroundmdx.run
.
string
(string
) -- A compiled mdx documentopts
(RunOpts
, optional) -- configurationA module (RMDXModule
) of renderable components
mdx
Compiles an ast to mdx.
mdast
Parses mdx to an mdast.
hast
Parses mdx to an hast.
plain
Parses mdx to a plain string. (This does not eval
the doc.)
tags
Returns a list of tag names from the doc. (This does not eval
the doc.)
utils
Additional defaults, helpers, components, etc.
CompileOpts
Extends CompileOptions
lazyImages
(boolean
, optional) -- load images lazilysafeMode
(boolean
, optional) -- extract script tags from HTMLBlock
scomponents
(Record<string, string>
, optional) -- an object of tag names to mdx.copyButtons
(Boolean
, optional) — add a copy button to code blocksRunOpts
Extends RunOptions
components
(Record<string, MDXModule>
, optional) -- a set of custom MDX componentsimports
(Record<string, unknown>
, optional) -- an set of modules to import globallyterms
(GlossaryTerm[]
, optional)variables
(Variables
, optional) -- an object containing user variablesRMDXModule
default
(() => MDXContent
) -- the MDX douments default exporttoc
(HastHeading[]
) -- a list of headings in the documentToc
(() => MDCContent
) -- a table of contents componentWe'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!
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
!
Running the 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.
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