1# react-markdown 2 3Renders Markdown as pure React components. 4 5[![npm version](https://img.shields.io/npm/v/react-markdown.svg?style=flat-square)](https://www.npmjs.com/package/react-markdown)[![Build Status](https://img.shields.io/travis/rexxars/react-markdown/master.svg?style=flat-square)](https://travis-ci.org/rexxars/react-markdown) 6 7Demo available at https://rexxars.github.io/react-markdown/ 8 9--- 10 11react-markdown is proudly sponsored by 12 13<a href="https://www.sanity.io/?utm_source=GitHub&utm_campaign=react-markdown" rel="nofollow" target="_blank"> 14 <img src="https://www.sanity.io/static/images/logo_red.svg?v=2" width="300"><br /> 15 Sanity: The Headless CMS Construction Kit 16</a> 17 18--- 19 20## Installing 21 22``` 23npm install --save react-markdown 24``` 25 26## Basic usage 27 28```js 29const React = require('react') 30const ReactDOM = require('react-dom') 31const ReactMarkdown = require('react-markdown') 32 33const input = '# This is a header\n\nAnd this is a paragraph' 34 35ReactDOM.render(<ReactMarkdown source={input} />, document.getElementById('container')) 36``` 37 38## Upgrading to 4.0 39 40Should be straightforward. You might need to alter you code slightly if you: 41 42- Are using `allowedTypes` (add `text` to the list) 43- Rely on there being a container `<div>` without a class name around your rendered markdown 44- Have implemented a custom `text` renderer 45 46See [CHANGELOG](CHANGELOG.md) for more details. 47 48## Notes 49 50If you don't need to render HTML, this component does not use `dangerouslySetInnerHTML` at all - 51this is a Good Thing™. 52 53## Options 54 55- `source` or `children` - _string_ The Markdown source to parse (**required**) 56- `className` - _string_ Class name of the container element. If none is passed, a container will not be rendered. 57- `escapeHtml` - _boolean_ Setting to `false` will cause HTML to be rendered (see notes below about proper HTML support). Be aware that setting this to `false` might cause security issues if the 58 input is user-generated. Use at your own risk. (default: `true`). 59- `skipHtml` - _boolean_ Setting to `true` will skip inlined and blocks of HTML (default: `false`). 60- `sourcePos` - _boolean_ Setting to `true` will add `data-sourcepos` attributes to all elements, 61 indicating where in the markdown source they were rendered from (default: `false`). 62- `rawSourcePos` - _boolean_ Setting to `true` will pass a `sourcePosition` property to all renderers with structured source position information (default: `false`). 63- `includeNodeIndex` - _boolean_ Setting to `true` will pass `index` and `parentChildCount` props to all renderers (default: `false`). 64- `allowedTypes` - _array_ Defines which types of nodes should be allowed (rendered). (default: all 65 types). 66- `disallowedTypes` - _array_ Defines which types of nodes should be disallowed (not rendered). 67 (default: none). 68- `unwrapDisallowed` - _boolean_ Setting to `true` will try to extract/unwrap the children of 69 disallowed nodes. For instance, if disallowing `Strong`, the default behaviour is to simply skip 70 the text within the strong altogether, while the behaviour some might want is to simply have the 71 text returned without the strong wrapping it. (default: `false`) 72- `allowNode` - _function_ Function execute if in order to determine if the node should be allowed. 73 Ran prior to checking `allowedTypes`/`disallowedTypes`. Returning a truthy value will allow the 74 node to be included. Note that if this function returns `true` and the type is not in 75 `allowedTypes` (or specified as a `disallowedType`), it won't be included. The function will 76 receive three arguments argument (`node`, `index`, `parent`), where `node` contains different 77 properties depending on the node type. 78- `linkTarget` - _function|string_ Sets the default target attribute for links. If a function is 79 provided, it will be called with `url`, `text`, and `title` and should return a string 80 (e.g. `_blank` for a new tab). Default is `undefined` (no target attribute). 81- `transformLinkUri` - _function|null_ Function that gets called for each encountered link with a 82 single argument - `uri`. The returned value is used in place of the original. The default link URI 83 transformer acts as an XSS-filter, neutralizing things like `javascript:`, `vbscript:` and `file:` 84 protocols. If you specify a custom function, this default filter won't be called, but you can 85 access it as `require('react-markdown').uriTransformer`. If you want to disable the default 86 transformer, pass `null` to this option. 87- `transformImageUri` - _function|null_ Function that gets called for each encountered image with a 88 single argument - `uri`. The returned value is used in place of the original. 89- `renderers` - _object_ An object where the keys represent the node type and the value is a React 90 component. The object is merged with the default renderers. The props passed to the component 91 varies based on the type of node. 92- `plugins` - _array_ An array of unified/remark parser plugins. If you need to pass options to the plugin, pass an array with two elements, the first being the plugin and the second being the options - for instance: `{plugins: [[require('remark-shortcodes'), {your: 'options'}]]`. (default: `[]`) Note that [not all plugins can be used](https://github.com/rexxars/react-markdown/issues/188#issuecomment-404710893). 93- `parserOptions` - _object_ An object containing options to pass to [remark-parse](https://github.com/remarkjs/remark/tree/master/packages/remark-parse). 94 95## Parsing HTML 96 97If you are in a trusted environment and want to parse and render HTML, you will want to use the `html-parser` plugin. For a default configuration, import `react-markdown/with-html` instead of the default: 98 99```js 100const ReactMarkdown = require('react-markdown/with-html') 101 102const markdown = ` 103This block of Markdown contains <a href="https://en.wikipedia.org/wiki/HTML">HTML</a>, and will require the <code>html-parser</code> AST plugin to be loaded, in addition to setting the <code class="prop">escapeHtml</code> property to false. 104` 105 106<ReactMarkdown 107 source={markdown} 108 escapeHtml={false} 109/> 110``` 111 112If you want to specify options for the HTML parsing step, you can instead import the HTML parser plugin directly: 113 114```js 115const ReactMarkdown = require('react-markdown') 116const htmlParser = require('react-markdown/plugins/html-parser') 117 118// See https://github.com/aknuds1/html-to-react#with-custom-processing-instructions 119// for more info on the processing instructions 120const parseHtml = htmlParser({ 121 isValidNode: node => node.type !== 'script', 122 processingInstructions: [/* ... */] 123}) 124 125<ReactMarkdown 126 source={markdown} 127 escapeHtml={false} 128 astPlugins={[parseHtml]} 129/> 130``` 131 132## Node types 133 134The node types available are the following, and applies to both `renderers` and 135`allowedTypes`/`disallowedTypes`: 136 137- `root` - Root container element that contains the rendered markdown 138- `text` - Text rendered inside of other elements, such as paragraphs 139- `break` - Hard-break (`<br>`) 140- `paragraph` - Paragraph (`<p>`) 141- `emphasis` - Emphasis (`<em>`) 142- `strong` - Strong/bold (`<strong>`) 143- `thematicBreak` - Horizontal rule / thematic break (`<hr>`) 144- `blockquote` - Block quote (`<blockquote>`) 145- `delete` - Deleted/strike-through (`<del>`) 146- `link` - Link (`<a>`) 147- `image` - Image (`<img>`) 148- `linkReference` - Link (through a reference) (`<a>`) 149- `imageReference` - Image (through a reference) (`<img>`) 150- `table` - Table (`<table>`) 151- `tableHead` - Table head (`<thead>`) 152- `tableBody` - Table body (`<tbody>`) 153- `tableRow` - Table row (`<tr>`) 154- `tableCell` - Table cell (`<td>`/`<th>`) 155- `list` - List (`<ul>`/`<ol>`) 156- `listItem` - List item (`<li>`) 157- `definition` - Definition (not rendered by default) 158- `heading` - Heading (`<h1>`-`<h6>`) 159- `inlineCode` - Inline code (`<code>`) 160- `code` - Block of code (`<pre><code>`) 161- `html` - HTML node (Best-effort rendering) 162- `virtualHtml` - When not using the HTML parser plugin, a cheap and dirty approach to supporting simple HTML elements without a complete parser. 163- `parsedHtml` - When using the HTML parser plugin, HTML parsed to a React element. 164 165Note: Disallowing a node will also prevent the rendering of any children of that node, unless the 166`unwrapDisallowed` option is set to `true`. E.g., disallowing a paragraph will not render its 167children text nodes. 168 169## Developing 170 171```bash 172git clone git@github.com:rexxars/react-markdown.git 173cd react-markdown 174npm install 175npm test 176``` 177 178## License 179 180MIT © [Espen Hovlandsdal](https://espen.codes/) 181