quoeradem / remark-react

Compile Markdown to React with remark

remark-react

remark-react compiles markdown to React. Built on remark, 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. remark-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 remark-react

Table of Contents

• Programmatic

  • remark.use(react, options)

• Configuration

• Integrations

• License

Programmatic

remark.use(react, options)

Parameters

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

Let’s say example.js looks as follows:

var React = require('react'),
    remark = require('remark'),
    reactRenderer = require('remark-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'>
                {remark().use(reactRenderer).processSync(this.state.text).contents}
            </div>
        </div>);
    }
});

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

Configuration

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

• sanitize (object or boolean, default: undefined) — Sanitation schema to use. Passed to hast-util-sanitize. The default schema, if none or true is passed, adheres to GitHub’s sanitation rules. If false is passed, it does not sanitize input.

• prefix (string, default: h-) — React key.

• createElement (Function, default: require('react').createElement) — Function to use to create elements.

• remarkReactComponents (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>:

  remarkReactComponents: {
    a: MyLink,
    p: MyParagraph
  }

  Note: as GFM uses align on td and th, and React doesn’t like that, we overwrite them through remarkReactComponents to use style.textAlign instead. This means that if you set td or td, you’ll need to handle align yourself.

• toHast (object, default: {}) — Provides options for transforming MDAST document to HAST. See mdast-util-to-hast for settings.

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

Integrations

remark-react works great with:

• remark-toc, which generates tables of contents;

• remark-github, which generates references to GitHub issues, PRs, users, and more;

• ...and more.

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

Additionally, syntax highlighting can be included (completely virtual) with remark-react-lowlight.

License

MIT © Titus Wormer, modified by Tom MacWright and Mapbox