@jeremybarbet/react-native-markdown-display v6.0.4

React Native Markdown Display

It a 100% compatible CommonMark renderer, a react-native markdown renderer done right. This is not a web-view markdown renderer but a renderer that uses native components for all its elements. These components can be overwritten and styled as needed.

Compatibility with react-native-markdown-renderer

This is intended to be a replacement for react-native-markdown-renderer, with a variety of bug fixes and enhancements - Due to how the new style rules work, there may be some tweaking needed, see how to style stuff section below

Install

Yarn

yarn add react-native-markdown-display

NPM

npm install -S react-native-markdown-display

Get Started

import react from 'react';
import { PureComponent } from 'react-native';
import Markdown from 'react-native-markdown-display';

const copy = `# h1 Heading 8-)

**This is some bold text!**

This is normal text
`;

export default class Page extends PureComponent {
  render() {
    return (
      <Markdown>{copy}</Markdown>
    );
  }
}

Props and Functions

The <Markdown> object takes the following common props:

And some additional, less used options:

Syntax Support

  # h1 Heading 8-)
  ## h2 Heading
  ### h3 Heading
  #### h4 Heading
  ##### h5 Heading
  ###### h6 Heading

  Some text above
  ___

  Some text in the middle

  ---

  Some text below

  **This is bold text**

  __This is bold text__

  *This is italic text*

  _This is italic text_

  ~~Strikethrough~~

  > Blockquotes can also be nested...
  >> ...by using additional greater-than signs right next to each other...
  > > > ...or with spaces between arrows.

  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
      - Nulla volutpat aliquam velit
  + Very easy!

  Ordered

  1. Lorem ipsum dolor sit amet
  2. Consectetur adipiscing elit
  3. Integer molestie lorem at massa

  Start numbering with offset:

  57. foo
  58. bar

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
| --- | ---
| <img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/ios-7.png"/>  | <img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/android-7.png"/>  

</p>
</details>


<details><summary>Tables</summary>
<p>

Right aligned columns

| iOS | Android
| --- | ---
| <img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/ios-8.png"/>  | <img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/android-8.png"/>  

</p>
</details>

<details><summary>Links</summary>
<p>

link text

link with title

Autoconverted link https://www.google.com (enable linkify to see)

| iOS | Android
| --- | ---
| <img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/ios-9.png"/>  | <img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/android-9.png"/>  

</p>
</details>

<details><summary>Images</summary>
<p>

Like links, Images also have a footnote style syntax

With a reference later in the document defining the URL location:

| iOS | Android
| --- | ---
| <img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/ios-10.png"/>  | <img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/android-10.png"/>  

</p>
</details>


<details><summary>Typographic Replacements</summary>
<p>

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
| --- | ---
| <img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/ios-3.png"/>  | <img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/android-3.png"/>  

</p>
</details>


<details><summary>Plugins and Extensions</summary>
<p>

  Plugins for **extra** syntax support - [see plugins](https://www.npmjs.com/browse/keyword/markdown-it-plugin) for the markdown-it library that this library is built on.

</p>
</details>


<details><summary>All Markdown for Testing</summary>
<p>

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
    • Nulla volutpat aliquam velit

• Very easy!

  Ordered

1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit

3. Integer molestie lorem at massa

   Start numbering with offset:

4. foo

5. 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

Right aligned columns

Links

link text

link with title

Autoconverted link https://www.google.com (enable linkify to see)

Images

Like links, Images also have a footnote style syntax

With a reference later in the document defining the URL location:

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'

</p>
</details>


# Rules and Styles

### How to style stuff

Text styles are applied in a way that makes it much more convenient to manage changes to global styles while also allowing fine tuning of individual elements.

Think of the implementation like applying styles in CSS. changes to the `body` effect everything, but can be overwritten further down the style / component tree.

**Be careful when styling 'text':** the text rule is not applied to all rendered text, most notably list bullet points. If you want to, for instance, color all text, change the `body` style.


<details><summary>Example</summary>
<p>

<img src="https://github.com/iamacup/react-native-markdown-display/raw/master/doc/images/style-example.png"/> 

```jsx
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 (
    <>
      <SafeAreaView>
        <View style={{marginHorizontal: 20}}>
          <Markdown
            mergeStyle={true} 
            style={{
              body: {color: 'red', fontSize: 10},
              heading1: {color: 'purple'},
              code_block: {color: 'black', fontSize: 14}
            }}
          >
            {copy}
          </Markdown>
        </View>
      </SafeAreaView>
    </>
  );
};

Styles

Styles are used to override how certain rules are styled. The existing implementation is here

NOTE: By default styles are merged with the existing implementation, to change this, see the mergeStyle prop

import react from 'react';
import {View, PureComponent, Text} from 'react-native';
import Markdown from 'react-native-markdown-display';
import { StyleSheet } from 'react-native';

const styles = StyleSheet.create({
  heading: {
    borderBottomWidth: 1,
    borderColor: '#000000',
  },
  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. |
`;

export default class Page extends PureComponent {
  render() {
    return (
      <Markdown style={styles}>{copy}</Markdown>
    );
  }
}

Rules

Rules are used to specify how you want certain elements to be displayed. The existing implementation is here

import react from 'react';
import {View, PureComponent, Text} from 'react-native';
import Markdown, {getUniqueID} from 'react-native-markdown-display';

const rules = {
    heading1: (node, children, parent, styles) =>
      <Text key={getUniqueID()} style={[styles.heading, styles.heading1]}>
        [{children}]
      </Text>,
    heading2: (node, children, parent, styles) =>
      <Text key={getUniqueID()} style={[styles.heading, styles.heading2]}>
        [{children}]
      </Text>,
    heading3: (node, children, parent, styles) =>
      <Text key={getUniqueID()} style={[styles.heading, styles.heading3]}>
        [{children}]
      </Text>,
};

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. |
`;

export default class Page extends PureComponent {
  render() {
    return (
      <Markdown rules={rules}>{copy}</Markdown>
    );
  }
}

All rules and their associated styles:

Handling Links

Links, by default, will be handled with the import { Linking } from 'react-native'; import and Linking.openURL(url); call.

It is possible to overwrite this behaviour in one of two ways:

import react from 'react';
import { PureComponent } from 'react-native';
import Markdown from 'react-native-markdown-display';

const copy = `[This is a link!](https://github.com/iamacup/react-native-markdown-display/)`;

export default class Page extends PureComponent {
  onLinkPress = (url) => {
    if (url) {
      // some custom logic
    }
    
    // return true to open with `Linking.openURL
    // return false to handle it yourself
    return true
  }

  render() {
    return (
      <Markdown onLinkPress={this.onLinkPress}>{copy}</Markdown>
    );
  }
}

You will need to overwrite one or both of link and blocklink, the original defenitions can be found here

Something like this with yourCustomHandlerFunctionOrLogicHere:

import react from 'react';
import {View, PureComponent, Text} from 'react-native';
import Markdown, {getUniqueID} from 'react-native-markdown-display';

const rules = {
  link: (node, children, parent, styles) => {
    return (
      <Text key={node.key} style={styles.link} onPress={() => yourCustomHandlerFunctionOrLogicHere(node.attributes.href) }>
        {children}
      </Text>
    );
  },
};

const copy = `[This is a link!](https://github.com/iamacup/react-native-markdown-display/)`;

export default class Page extends PureComponent {
  render() {
    return (
      <Markdown rules={rules}>{copy}</Markdown>
    );
  }
}

Disabling Specific Types of Markdown

You can dissable any type of markdown you want, which is very useful in a mobile environment, by passing the markdownit property like below. Note that for convenience we also export the MarkdownIt instance so you don't have to include it as a project dependency directly just to remove some types of markdown.

This example will stop images and links.

import Markdown from 'react-native-markdown-display';
import MarkdownIt from 'react-native-markdown-display/src/MarkdownIt';

const copy = `
# This heading will show with formatting

[but this link will just](be displayed as this text)
`;

<Markdown
  markdownit={
    MarkdownIt({typographer: true}).disable([ 'link', 'image' ])
  }
>
  {copy}
</Markdown>

A full list of things you can turn off is here

TODO

• Code highlighting
• Provide options for customising image display (fit image)
• Rework styles and rules - the way it is all applied works but is annoying to, for instance, change the text color of everything.

Other Notes

This is a fork of react-native-markdown-renderer, a library that unfortunately has not been updated for some time so i took all of the outstanding pull requests from that library and tested + merged as necessary.