@readme/markdown
v7.9.0
Published
ReadMe's React-based Markdown parser
Downloads
14,587
Maintainers
Keywords
Readme
@readme/markdown
ReadMe's MDX rendering engine and custom component collection. (Use ReadMe? Learn more about our upcoming move to MDX!)
Getting Started
To use the engine, install it from NPM:
npm install --save @readme/markdown
Then compile
and run
your MDX:
import RMDX from '@readme/markdown';
export default ({ body }) => (
<div className="markdown-body">
{RMDX.run(RMDX.compile(body))}
</div>
);
API
compile
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 documentopts
(CompileOpts
, optional)—a configuration object
Returns
A string of compiled Javascript module code.
run
[!CAUTION] This is essentially a wrapper around
mdx.run
and it willeval
the compiled MDX. Make sure you only callrun
on safe syntax from a trusted author!Parameters
string
(string
)—a compiled mdx documentopts
(RunOpts
, optional)—configurationReturns
An
RMDXModule
of renderable components.
mdx
Compiles an AST to a string of MDX syntax.
Parameters
tree
(object
)—an abstract syntax treeopts
(Options
)—remark-stringify
configuration.
Returns
An MDX string.
Other Methods
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 noteval
the doc.)tags
: get a list of tag names from the doc. (This does noteval
the doc.)utils
: additional defaults, helper methods, components, and so on.
Types
CompileOpts
Extends CompileOptions
Additional Properties
lazyImages
(boolean
, optional)—load images lazilysafeMode
(boolean
, optional)—extract script tags fromHTMLBlock
scomponents
(Record<string, string>
, optional)—an object of tag names to mdx.copyButtons
(Boolean
, optional) — add a copy button to code blocks
RunOpts
Extends RunOptions
Additional Properties
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 variables
RMDXModule
Properties
default
(() => MDXContent
)—the MDX douments default exporttoc
(HastHeading[]
)—a list of headings in the documentToc
(() => 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.