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 = mdast = reactRenderer = ; var App = React; React;
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 ofelement: Component
key-value pairs. For example, to output<MyLink>
components instead of<a>
, and<MyParagraph>
instead of<p>
:mdastReactComponents:a: MyLinkp: 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:
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.
License
MIT © Titus Wormer, modified by Tom MacWright and Mapbox