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
Table of Contents
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.
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": {
"html": {
"sanitize": false,
"xhtml": false,
"entities": "numbers"
}
},
"settings": {
"commonmark": true
}
}
Where the object at plugins.html
are the options for mdast-html.
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-html looks for an
attributes
object on each node it compiles and adds the found properties
as HTML attributes on the compiled tag.
License
MIT © Titus Wormer, modified by Tom MacWright and Mapbox