react-markdown

What is react-markdown?

The react-markdown npm package is a markdown renderer for React applications. It allows you to take Markdown content and render it as React components. This is useful for content-driven applications, such as blogs or documentation sites, where you want to allow content creators to write in Markdown and then display that content within your React application.

What are react-markdown's main functionalities?

Rendering Markdown

This feature allows you to render standard Markdown text as React components. The example code shows how to import the ReactMarkdown component and use it to render a simple piece of Markdown text.

import React from 'react';
import ReactMarkdown from 'react-markdown';

const markdown = '# Hello, *world*!';

function App() {
  return <ReactMarkdown>{markdown}</ReactMarkdown>;
}

export default App;

Custom Renderers

This feature allows you to define custom renderers for different Markdown elements. In the example, a custom renderer is provided for 'h1' elements, which renders them with a blue color.

import React from 'react';
import ReactMarkdown from 'react-markdown';

const markdown = '# Hello, *world*!';

function HeadingRenderer(props) {
  return <h1 style={{ color: 'blue' }}>{props.children}</h1>;
}

function App() {
  return (
    <ReactMarkdown
      components={{
        h1: HeadingRenderer
      }}
    >
      {markdown}
    </ReactMarkdown>
  );
}

export default App;

Inline HTML and Skip HTML

This feature allows you to include or exclude inline HTML within your Markdown content. The example code demonstrates how to skip rendering inline HTML by using the 'skipHtml' prop.

import React from 'react';
import ReactMarkdown from 'react-markdown';

const markdown = 'This is a paragraph with <span style="color: red;">inline HTML</span>.';

function App() {
  return (
    <ReactMarkdown skipHtml>
      {markdown}
    </ReactMarkdown>
  );
}

export default App;

Plugins

This feature allows you to extend the functionality of react-markdown with plugins. The example code shows how to use the 'remark-gfm' plugin to add support for GitHub Flavored Markdown (GFM) task lists.

import React from 'react';
import ReactMarkdown from 'react-markdown';
import gfm from 'remark-gfm';

const markdown = 'This supports GitHub Flavored Markdown (GFM)\n\n- [ ] todo\n- [x] done';

function App() {
  return <ReactMarkdown remarkPlugins={[gfm]}>{markdown}</ReactMarkdown>;
}

export default App;

Other packages similar to react-markdown

marked

Marked is a low-level markdown compiler for parsing markdown without caching or blocking for long periods of time. It is less React-specific than react-markdown and requires additional work to integrate with React.

remarkable

Remarkable is a highly configurable markdown parser and compiler. It offers similar functionality to react-markdown but is not designed specifically for React and does not render React components out of the box.

markdown-to-jsx

markdown-to-jsx is another React component that lets you render Markdown as React components. It is similar to react-markdown but offers a simpler API with less configurability, which might be preferable for simpler use cases.

README

react-markdown

Renders Markdown as pure React components.

Demo available at http://rexxars.github.io/react-markdown/

Installing

npm install --save react-markdown

Basic usage

var React = require('react');
var ReactDOM = require('react-dom');
var ReactMarkdown = require('react-markdown');

var input = '# This is a header\n\nAnd this is a paragraph';

ReactDOM.render(
    <ReactMarkdown source={input} />,
    document.getElementById('container')
);

Important note

If you are using Webpack, you need to enable a JSON-loader. To do so, first npm install --save json-loader, then add the loader to your webpack config:

{
    module: {
        loaders: [{
            test: /\.json$/,
            loader: 'json'
        }]
    }
}

Notes

If you either set escapeHtml or skipHtml to true, this component does not use dangerouslySetInnerHTML at all - this is a Good Thing™.

Options

• source - string The Markdown source to parse (required)
• className - string Class name of the container element (default: '').
• containerTagName - string Tag name for the container element, since Markdown can have many root-level elements, the component need to wrap them in something (default: div).
• escapeHtml - boolean Setting to true will escape HTML blocks, rendering plain text instead of inserting the blocks as raw HTML (default: false).
• skipHtml - boolean Setting to true will skip inlined and blocks of HTML (default: false).
• sourcePos - boolean Setting to true will add data-sourcepos attributes to all elements, indicating where in the markdown source they were rendered from (default: false).
• softBreak - string Setting to br will create <br> tags instead of newlines (default: \n).
• allowedTypes - array Defines which types of nodes should be allowed (rendered). (default: all types).
• disallowedTypes - array Defines which types of nodes should be disallowed (not rendered). (default: none).
• unwrapDisallowed - boolean Setting to true will try to extract/unwrap the children of disallowed nodes. For instance, if disallowing Strong, the default behaviour is to simply skip the text within the strong altogether, while the behaviour some might want is to simply have the text returned without the strong wrapping it. (default: false)
• allowNode - function Function execute if in order to determine if the node should be allowed. Ran prior to checking allowedTypes/disallowedTypes. Returning a truthy value will allow the node to be included. Note that if this function returns true and the type is not in allowedTypes (or specified as a disallowedType), it won't be included. The function will get a single object argument (node), which includes the following properties:
  • type - string The type of node - same ones accepted in allowedTypes and disallowedTypes
  • renderer - string The resolved renderer for this node
  • props - object Properties for this node
  • `children* - array Array of children
• renderers - object An object where the keys represent the node type and the value is a React component. The object is merged with the default renderers. The props passed to the component varies based on the type of node. See the type renderer options of commonmark-react-renderer for more details.
• transformLinkUri - function|null Function that gets called for each encountered link with a single argument - uri. The returned value is used in place of the original. The default link URI transformer acts as an XSS-filter, neutralizing things like javascript:, vbscript: and file: protocols. If you specify a custom function, this default filter won't be called, but you can access it as require('react-markdown').uriTransformer. If you want to disable the default transformer, pass null to this option.

The possible types of elements that can be allowed/disallowed are:

• HtmlInline - Inline HTML
• HtmlBlock - Block of HTML
• Text - Text nodes (inside of paragraphs, list items etc)
• Paragraph - Paragraph nodes (<p>)
• Heading - Headers (<h1>, <h2> etc)
• Softbreak - Newlines
• Hardbreak - Hard line breaks (<br>)
• Link - Link nodes (<a>)
• Image - Image nodes (<img>)
• Emph - Emphasis nodes (<em>)
• Code - Inline code nodes (<code>)
• CodeBlock - Blocks of code (<code>)
• BlockQuote - Block quotes (<blockquote>)
• List - List nodes (<ol>, <ul>)
• Item - List item nodes (<li>)
• Strong - Strong/bold nodes (<strong>)
• ThematicBreak - Horizontal rule nodes (<hr>)

Note: Disallowing a node will also prevent the rendering of any children of that node, unless the unwrapDisallowed option is set to true. Eg, disallowing a paragraph will not render it's children text nodes.

Developing

git clone [e-mail]:rexxars/react-markdown.git
cd react-markdown
npm install
npm test

License

MIT-licensed. See LICENSE.

Changelog

2.0.0 - 2016-02-21

Changed

• Breaking change: The renderer now requires Node 0.14 or higher. This is because the renderer uses stateless components internally.
• Breaking change: allowNode now receives different properties in the options argument. See README.md for more details.
• Breaking change: CommonMark has changed some type names. Html is now HtmlInline, Header is now Heading and HorizontalRule is now ThematicBreak. This affects the allowedTypes and disallowedTypes options.
• Breaking change: A bug in the allowedTypes/disallowedTypes and allowNode options made them only applicable to certain types. In this version, all types are filtered, as expected.
• Breaking change: Link URIs are now filtered through an XSS-filter by default, prefixing “dangerous” protocols such as javascript: with x- (eg: javascript:alert('foo') turns into x-javascript:alert('foo')). This can be overridden with the transformLinkUri-option. Pass null to disable the feature or a custom function to replace the built-in behaviour.

Added

• New renderers option allows you to customize which React component should be used for rendering given types. See README.md for more details. (Espen Hovlandsdal / Guillaume Plique)
• New unwrapDisallowed option allows you to select if the contents of a disallowed node should be “unwrapped” (placed into the disallowed node position). For instance, setting this option to true and disallowing a link would still render the text of the link, instead of the whole link node and all it’s children disappearing. (Espen Hovlandsdal)
• New transformLinkUri option allows you to transform URIs in links. By default, an XSS-filter is used, but you could also use this for use cases like transforming absolute to relative URLs, or similar. (Espen Hovlandsdal)