` object takes the following common props:
| Property | Default | Required | Description
| --- | --- | --- | ---
| `children` | N/A | `true` | The markdown string to render, or the [pre-processed tree](#pre-processing)
| `style` | [source](https://github.com/iamacup/react-native-markdown-display/blob/master/src/lib/styles.js) | `false` | An object to override the styling for the various rules, [see style section below](#rules-and-styles) for more info
| `mergeStyle` | `true` | `false` | If true, when a style is supplied, the individual items are merged with the default styles instead of overwriting them
| `rules` | [source](https://github.com/iamacup/react-native-markdown-display/blob/master/src/lib/renderRules.js) | `false` | An object of rules that specify how to render each markdown item, [see rules section below](#rules) for more info
| `onLinkPress` | `import { Linking } from 'react-native';` and `Linking.openURL(url);` | `false` | A handler function to change click behaviour, [see handling links section below](#handling-links) for more info
| `debugPrintTree` | `false` | `false` | Will print the AST tree to the console to help you see what the markdown is being translated to
And some additional, less used options:
| Property | Default | Required | Description
| --- | --- | --- | ---
| `renderer` | `instanceOf(AstRenderer)` | `false` | Used to specify a custom renderer, you can not use the rules or styles props with a custom renderer.
| `markdownit` | `instanceOf(MarkdownIt)` | `false` | A custom markdownit instance with your configuration, default is `MarkdownIt({typographer: true})`
| `maxTopLevelChildren` | `null` | `false` | If defined as a number will only render out first `n` many top level children, then will try to render out `topLevelMaxExceededItem`
| `topLevelMaxExceededItem` | `...` | `false` | Will render when `maxTopLevelChildren` is hit. Make sure to give it a key!
| `allowedImageHandlers` | `['data:image/png;base64', 'data:image/gif;base64', 'data:image/jpeg;base64', 'https://', 'http://']` | `false` | Any image that does not start with one of these will have the `defaultImageHandler` value prepended to it (unless `defaultImageHandler` is null in which case it won't try to render anything)
| `defaultImageHandler` | `http://` | `false` | Will be prepended to an image url if it does not start with something in the `allowedImageHandlers` array, if this is set to null, it won't try to recover but will just not render anything instead.
# Syntax Support
Headings
```
# h1 Heading 8-)
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading
```
| iOS | Android
| --- | ---
| 
| 
Horizontal Rules
```
Some text above
___
Some text in the middle
---
Some text below
```
| iOS | Android
| --- | ---
| 
| 
Emphasis
```
**This is bold text**
__This is bold text__
*This is italic text*
_This is italic text_
~~Strikethrough~~
```
| iOS | Android
| --- | ---
| 
| 
Blockquotes
```
> Blockquotes can also be nested...
>> ...by using additional greater-than signs right next to each other...
> > > ...or with spaces between arrows.
```
| iOS | Android
| --- | ---
| 
| 
Lists
```
Unordered
+ Create a list by starting a line with `+`, `-`, or `*`
+ Sub-lists are made by indenting 2 spaces:
- Marker character change forces new list start:
* Ac tristique libero volutpat at
+ Facilisis in pretium nisl aliquet. This is a very long list item that will surely wrap onto the next line.
- Nulla volutpat aliquam velit
+ Very easy!
Ordered
1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit. This is a very long list item that will surely wrap onto the next line.
3. Integer molestie lorem at massa
Start numbering with offset:
57. foo
58. bar
```
| iOS | Android
| --- | ---
| 
| 
Code
```
Inline \`code\`
Indented code
// Some comments
line 1 of code
line 2 of code
line 3 of code
Block code "fences"
\`\`\`
Sample text here...
\`\`\`
Syntax highlighting
\`\`\` js
var foo = function (bar) {
return bar++;
};
console.log(foo(5));
\`\`\`
```
| iOS | Android
| --- | ---
| 
| 
Tables
```
| Option | Description |
| ------ | ----------- |
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
Right aligned columns
| Option | Description |
| ------:| -----------:|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
```
| iOS | Android
| --- | ---
| 
| 
Links
```
[link text](https://www.google.com)
[link with title](https://www.google.com "title text!")
Autoconverted link https://www.google.com (enable linkify to see)
```
| iOS | Android
| --- | ---
| 
| 
Images
```
Like links, Images also have a footnote style syntax
![Alt text][id]
With a reference later in the document defining the URL location:
[id]: https://octodex.github.com/images/dojocat.jpg "The Dojocat"
```
| iOS | Android
| --- | ---
| 
| 
Typographic Replacements
```
Enable typographer option to see result.
(c) (C) (r) (R) (tm) (TM) (p) (P) +-
test.. test... test..... test?..... test!....
!!!!!! ???? ,, -- ---
"Smartypants, double quotes" and 'single quotes'
```
| iOS | Android
| --- | ---
| 
| 
Plugins and Extensions
Plugins for **extra** syntax support can be added using any markdown-it compatible plugins - [see plugins](https://www.npmjs.com/browse/keyword/markdown-it-plugin) for documentation from markdown-it. An example for integration follows:
#### Step 1
Identify the new components and integrate the plugin with a rendered component. We can use the `debugPrintTree` property to see what rules we are rendering:
```jsx
import React from 'react';
import { SafeAreaView, ScrollView, StatusBar } from 'react-native';
import Markdown, { MarkdownIt } from 'react-native-markdown-display';
import blockEmbedPlugin from 'markdown-it-block-embed';
const markdownItInstance =
MarkdownIt({typographer: true})
.use(blockEmbedPlugin, {
containerClassName: "video-embed"
});
const copy = `
# Some header
@[youtube](lJIrF4YjHfQ)
`;
const App: () => React$Node = () => {
return (
<>
{copy}
);
};
export default App;
```
In the console, we will see the following rendered tree:
```
body
-heading1
--textgroup
---text
-video
```
With the following error message:
```
Warning, unknown render rule encountered: video. 'unknown' render rule used (by default, returns null - nothing rendered)
```
#### Step 2
We need to create the **render rules** and **styles** to handle this new **'video'** component
```jsx
import React from 'react';
import { SafeAreaView, ScrollView, StatusBar } from 'react-native';
import Markdown, { MarkdownIt } from 'react-native-markdown-display';
import blockEmbedPlugin from 'markdown-it-block-embed';
const markdownItInstance =
MarkdownIt({typographer: true})
.use(blockEmbedPlugin, {
containerClassName: "video-embed"
});
const copy = `
# Some header
@[youtube](lJIrF4YjHfQ)
`;
const App: () => React$Node = () => {
return (
<>
{
// examine the node properties to see what video we need to render
console.log(node); // expected output of this is in readme.md below this code snip
return (
Return a video component instead of this text component!
);
}
}}
>
{copy}
);
};
export default App;
```
And all of the video properties needed to render something meaningful are on the node, like this:
```
{type: "video", sourceType: "video", sourceInfo: {…}, sourceMeta: null, block: true, …}
attributes: {}
block: true
children: []
content: ""
index: 1
key: "rnmr_1720a98f540_video"
markup: "@[youtube](lJIrF4YjHfQ)"
sourceInfo:
service: YouTubeService
env: PluginEnvironment {md: MarkdownIt, options: {…}, services: {…}}
name: "youtube"
options:
height: 390
width: 640
serviceName: "youtube"
videoID: "lJIrF4YjHfQ"
videoReference: "lJIrF4YjHfQ"
sourceMeta: null
sourceType: "video"
tokenIndex: 5
type: "video"
```
#### Other Debugging
You can do some additional debugging of what the markdown instance is spitting out like this:
```jsx
import Markdown, { MarkdownIt } from 'react-native-markdown-display';
import blockEmbedPlugin from 'markdown-it-block-embed';
const markdownItInstance =
MarkdownIt({typographer: true})
.use(blockEmbedPlugin, {
containerClassName: "video-embed"
});
const copy = `
# Some header
@[youtube](lJIrF4YjHfQ)
`;
// this shows you the tree that is used by the react-native-markdown-display
const astTree = markdownItInstance.parse(copy, {});
console.log(astTree);
//this contains the html that would be generated - not used by react-native-markdown-display but useful for reference
const html = markdownItInstance.render(copy);
console.log(html);
```
The above code will output something like this:
```
astTree:
(4) [Token, Token, Token, Token]
0: Token {type: "heading_open", tag: "h1", attrs: null, map: Array(2), nesting: 1, …}
1: Token {type: "inline", tag: "", attrs: null, map: Array(2), nesting: 0, …}
2: Token {type: "heading_close", tag: "h1", attrs: null, map: null, nesting: -1, …}
3: Token {type: "video", tag: "div", attrs: null, map: Array(2), nesting: 0, …}
length: 4
```
```
html:
Some header
```
All Markdown for Testing
This is all of the markdown in one place for testing that your applied styles work in all cases
```
Headings
# h1 Heading 8-)
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading
Horizontal Rules
Some text above
___
Some text in the middle
---
Some text below
Emphasis
**This is bold text**
__This is bold text__
*This is italic text*
_This is italic text_
~~Strikethrough~~
Blockquotes
> Blockquotes can also be nested...
>> ...by using additional greater-than signs right next to each other...
> > > ...or with spaces between arrows.
Lists
Unordered
+ Create a list by starting a line with `+`, `-`, or `*`
+ Sub-lists are made by indenting 2 spaces:
- Marker character change forces new list start:
* Ac tristique libero volutpat at
+ Facilisis in pretium nisl aliquet. This is a very long list item that will surely wrap onto the next line.
- Nulla volutpat aliquam velit
+ Very easy!
Ordered
1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit. This is a very long list item that will surely wrap onto the next line.
3. Integer molestie lorem at massa
Start numbering with offset:
57. foo
58. bar
Code
Inline \`code\`
Indented code
// Some comments
line 1 of code
line 2 of code
line 3 of code
Block code "fences"
\`\`\`
Sample text here...
\`\`\`
Syntax highlighting
\`\`\` js
var foo = function (bar) {
return bar++;
};
console.log(foo(5));
\`\`\`
Tables
| Option | Description |
| ------ | ----------- |
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
Right aligned columns
| Option | Description |
| ------:| -----------:|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
Links
[link text](https://www.google.com)
[link with title](https://www.google.com "title text!")
Autoconverted link https://www.google.com (enable linkify to see)
Images
Like links, Images also have a footnote style syntax
![Alt text][id]
With a reference later in the document defining the URL location:
[id]: https://octodex.github.com/images/dojocat.jpg "The Dojocat"
Typographic Replacements
Enable typographer option to see result.
(c) (C) (r) (R) (tm) (TM) (p) (P) +-
test.. test... test..... test?..... test!....
!!!!!! ???? ,, -- ---
"Smartypants, double quotes" and 'single quotes'
```
Example
```jsx
import React from 'react';
import { SafeAreaView, ScrollView, StatusBar } from 'react-native';
import Markdown from 'react-native-markdown-display';
const copy = `
This is some text which is red because of the body style, which is also really small!
\`\`\`
//This is a code block woooo
const cool = () => {
console.log('????');
};
\`\`\`
and some more small text
# This is a h1
## this is a h2
### this is a h3
`;
const App: () => React$Node = () => {
return (
<>
{copy}
);
};
export default App;
```
Example Implementation
```jsx
import React from 'react';
import { SafeAreaView, ScrollView, StatusBar, StyleSheet } from 'react-native';
import Markdown from 'react-native-markdown-display';
const styles = StyleSheet.create({
heading1: {
fontSize: 32,
backgroundColor: '#000000',
color: '#FFFFFF',
},
heading2: {
fontSize: 24,
},
heading3: {
fontSize: 18,
},
heading4: {
fontSize: 16,
},
heading5: {
fontSize: 13,
},
heading6: {
fontSize: 11,
}
});
const copy = `
# h1 Heading 8-)
## h2 Heading 8-)
### h3 Heading 8-)
| Option | Description |
| ------ | ----------- |
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
`;
const App: () => React$Node = () => {
return (
<>
{copy}
);
};
export default App;
```
Example Implementation
```jsx
import React from 'react';
import { SafeAreaView, ScrollView, StatusBar, Text } from 'react-native';
import Markdown from 'react-native-markdown-display';
const rules = {
heading1: (node, children, parent, styles) =>
>> H1 TEXT HERE >> "{children}"
,
heading2: (node, children, parent, styles) =>
>> H2 TEXT HERE >> "{children}"
,
heading3: (node, children, parent, styles) =>
>> H3 TEXT HERE >> "{children}"
,
};
const copy = `
# h1 Heading 8-)
## h2 Heading 8-)
### h3 Heading 8-)
| Option | Description |
| ------ | ----------- |
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
`;
const App: () => React$Node = () => {
return (
<>
{copy}
);
};
export default App;
```
onLinkPress Callback
```jsx
import React from 'react';
import { SafeAreaView, ScrollView, StatusBar } from 'react-native';
import Markdown from 'react-native-markdown-display';
const copy = `[This is a link!](https://github.com/iamacup/react-native-markdown-display/)`;
const onLinkPress = (url) => {
if (url) {
// some custom logic
return false;
}
// return true to open with `Linking.openURL
// return false to handle it yourself
return true
}
const App: () => React$Node = () => {
return (
<>
{copy}
);
};
export default App;
```
Using a Custom Rule
You will need to overwrite one or both of `link` and `blocklink`, the original defenitions can be [found here](https://github.com/iamacup/react-native-markdown-display/blob/master/src/lib/renderRules.js)
Something like this with `yourCustomHandlerFunctionOrLogicHere`:
```jsx
import React from 'react';
import { SafeAreaView, ScrollView, StatusBar, Text } from 'react-native';
import Markdown from 'react-native-markdown-display';
const copy = `[This is a link!](https://github.com/iamacup/react-native-markdown-display/)`;
const rules = {
link: (node, children, parent, styles) => {
return (
yourCustomHandlerFunctionOrLogicHere(node.attributes.href) }>
{children}
);
},
};
const App: () => React$Node = () => {
return (
<>
{copy}
);
};
export default App;
```