Merge pull request #79 from yaycmyk/html-handling

Inline HTML handling, function signature changes for 4.0

README.md

@@ -1,53 +1,69 @@
-# markdown to jsx converter
+# markdown to jsx compiler
 
 ![build status](https://api.travis-ci.org/yaycmyk/markdown-to-jsx.svg) [![codecov](https://codecov.io/gh/yaycmyk/markdown-to-jsx/branch/master/graph/badge.svg)](https://codecov.io/gh/yaycmyk/markdown-to-jsx)
 
-
 Enables the safe parsing of markdown into proper React JSX objects, so you don't need to use a pattern like `dangerouslySetInnerHTML` and potentially open your application up to security issues.
 
-The only exception is arbitrary HTML in the markdown (kind of an antipattern), which will still use the unsafe method.
+The only exception is arbitrary block-level HTML in the markdown (considered a markdown antipattern), which will still use the unsafe method.
+
+Uses [remark-parse](https://github.com/wooorm/remark-parse) under the hood to parse markdown into a consistent AST format. The following [remark](https://github.com/wooorm/remark) settings are set by `markdown-to-jsx`:
 
-Uses [remark](https://github.com/wooorm/remark) under the hood to parse markdown into a consistent AST format.
+- footnotes: true
+- gfm: true
+- position: false
 
 Requires React >= 0.14.
 
 ## Usage
 
-```js
-import converter from 'markdown-to-jsx';
-import React from 'react';
-import {render} from 'react-dom';
+The default export function signature:
 
-render(converter('# Hello world!'), document.body);
+```js
+compiler(markdown: string, options: object?)
 ```
 
-[remark options](https://github.com/wooorm/remark#remarkprocessvalue-options-done) can be passed as the second argument:
+ES6-style usage:
 
 ```js
-converter('* abc\n* def\n* ghi', {bullet: '*'});
+import compiler from 'markdown-to-jsx';
+import React from 'react';
+import {render} from 'react-dom';
+
+render(compiler('# Hello world!'), document.body);
 ```
 
-_Footnotes are enabled by default as of `[email protected]`._
+Override a particular HTML tag's output:
 
-## Overriding tags and adding props
+```jsx
+import compiler from 'markdown-to-jsx';
+import React from 'react';
+import {render} from 'react-dom';
 
-As of `[email protected]`, it's now possible to selectively override a given HTML tag's JSX representation. This is done through a new third argument to the converter: an object made of keys, each being the lowercase html tag name (p, figure, a, etc.) to be overridden.
+// surprise, it's a div instead!
+const MyParagraph = ({children, ...props}) => (<div {...props}>{children}</div>);
+
+render(
+    compiler('# Hello world!', {
+        overrides: {
+            h1: {
+                component: MyParagraph,
+                props: {
+                    className: 'foo',
+                },
+            },
+        },
+    }), document.body
+);
 
-Each override can be given a `component` that will be substituted for the tag name and/or `props` that will be applied as you would expect.
+/*
+    renders:
 
-```js
-converter('Hello there!', {}, {
-    p: {
-        component: MyParagraph,
-        props: {
-            className: 'foo'
-        },
-    }
-});
+    <div class="foo">
+        Hello World
+    </div>
+ */
 ```
 
-The code above will replace all emitted `<p>` tags with the given component `MyParagraph`, and add the `className` specified in `props`.
-
 Depending on the type of element, there are some props that must be preserved to ensure the markdown is converted as intended. They are:
 
 - `a`: `title`, `href`
@@ -58,8 +74,4 @@ Depending on the type of element, there are some props that must be preserved to
 
 Any conflicts between passed `props` and the specific properties above will be resolved in favor of `markdown-to-jsx`'s code.
 
-## Known Issues
-
-- remark's handling of arbitrary HTML causes nodes to be split, which causes garbage and malformed HTML - [Bug Ticket](https://github.com/wooorm/remark/issues/124)
-
 MIT