Getting Started

ReadMe's Markdown engine, with notes of GitHub, modern styles, and a hint of magic.

A remark-based Markdown engine for parsing and rendering ReadMe docs. (In fact, you're looking at it right now, since we've used it to render every doc in this project!)

npm install --save @readme/markdown

🧙‍ Backwards Compatible

Our old engine was based on a format we call "magic blocks". This was our custom, JSON-based syntax for writing rich components alongside plain-text Markdown. To provide seamless backwards-compatibility, the engine ships with a built-in parser for the older format so we can transpile it directly to our new ReadMe-flavored syntax.


By default, the Markdown library exports a function which takes a string of ReadMe-flavored markdown and returns a tree of React components:

import React from 'react';
import rdmd from '@readme/markdown';

export default ({ body }) => (
  <div className="markdown-body">



In addition to the default React processor, the package exports a few other methods for parsing and rendering ReadMe-flavored markdown:

import * as rdmd from '@readme/markdown';

This gives you various methods and utilities:

reactdefault; returns a VDOM React treetext, options
htmltransform markdown in to HTMLtext, options
asttransform markdown to an mdast objecttext, options
mdtransform mdast in to ReadMe-flavored markdownast, options


The utils export gives you access to various tools and configuration settings:

  • options
    a hash of default settings accepted by the rdmd engine.
    • markdownOptions—configuration object passed to remark
    • correctnewlines—flag to toggle newline transformation.
    • normalize—auto-normalize magic blocks before processing.
    • disableTokenizers—disable internal block or inline tokenizers.
  • <GlossaryContext/> and <VariablesContext/>
    React provider and consumer wrappers for user data injection.