Mdast-react NPM

mdast-react

mdast-react compiles markdown to React. Built on mdast, an extensively tested and pluggable parser.

Why? Using innerHTML and dangerouslySetInnerHTML in React.js is a common cause of XSS attacks: user input can include script tags and other kinds of active content that reaches across domains and harms security. mdast-react builds a DOM in React, using React.createElement: this means that you can display parsed & formatted Markdown content in an application without using dangerouslySetInnerHTML.

Installation

npm:

npm install mdast-react

Programmatic

mdast.use(react, options)

Parameters

react — This plugin;
options (Object?) — See below.

Let’s say example.js looks as follows:

var React = require('react'),
    mdast = require('mdast'),
    reactRenderer = require('mdast-react');

var App = React.createClass({
    getInitialState() {
        return { text: '# hello world' };
    },
    onChange(e) {
        this.setState({ text: e.target.value });
    },
    render() {
        return (<div>
            <textarea
                value={this.state.text}
                onChange={this.onChange} />
            <div id='preview'>
                {mdast().use(reactRenderer).process(this.state.text)}
            </div>
        </div>);
    }
});

React.render(<App />, document.getElementById('app'));

Configuration

All options, including the options object itself, are optional:

entities (true, 'numbers', or 'escape', default: true) — How to encode non-ASCII and HTML-escape characters: the default generates named entities (& > &); 'numbers' generates numbered entities (& > &), and 'escape' only encodes characters which are required by HTML to be escaped: &, <, >, ", ', and `, leaving non-ASCII characters untouched.
sanitize (boolean, default: false) — Whether or not to allow the use of HTML inside markdown.
mdastReactComponents (object, default: undefined) — Provides a way to override default elements (<a>, <p>, etc) by defining an object comprised of element: Component key-value pairs. For example, to output <MyLink> components instead of <a>, and <MyParagraph> instead of <p>:
```
mdastReactComponents: {
  a: MyLink,
  p: MyParagraph
}
```

These can passed to mdast.use() as a second argument.

You can define these in .mdastrc or package.json files too. An example .mdastrc file could look as follows:

{
  "plugins": {
    "react": {
        "sanitize": false,
        "xhtml": false,
        "entities": "numbers"
    }
  },
  "settings": {
    "commonmark": true
  }
}

Where the object at plugins.react are the options for mdast-react. The object at settings determines how mdast parses markdown code. Read more about the latter on mdast’s readme.

CommonMark

You still need to set commonmark: true in mdast’s options

CommonMark support is a goal but not (yet) a necessity. There are some (roughly 115 of 550, relating to inline precedence, lists, emphasis and strongness) issues which I’d like to cover in the future. Note that this sounds like a lot, but they have to do with obscure differences which do not often occur in the real world. Read more on some of the reasoning in doc/commonmark.md.

Integrations

mdast-react works great with:

mdast-toc, which generates tables of contents;
mdast-github, which generates references to GitHub issues, PRs, users, and more;
mdast-comment-config and mdast-yaml-config, which specify how HTML is compiled in the document itself;
...and more.

All mdast nodes can be compiled to HTML. In addition, mdast-react looks for an attributes object on each node it compiles and adds the found properties as HTML attributes on the compiled tag.