@alicloud/rc-markdown

Yet another react wrapper of markdown parse based on micromark.

Plugins built-in:

• micromark-extension-gfm - support GFM out of the box
• micromark-extension-directive - well, you might have to write some code to make it work

Other plugins, e.g. micromark-extension-math, you have to install it yourself and put it into props.extraExtensions:

import React from 'react';
import {
  math,
  mathHtml
} from 'micromark-extension-math';

import Markdown, {
  MarkdownExtension
} from '@alicloud/rc-markdown';

const extraExtensions: MarkdownExtension[] = [{
  syntax: math(),
  html: mathHtml()
}];

export default function MyMarkdown(): JSX.Element {
  return <Markdown {...{
    source: __YOUR_MARKDOWN_DOCUMENT_IN_STRING_FORMAT__,
    extraExtensions
  }} />;
}

Why 🙈

I used to use react-markdown, however it has these defects:

1. Its dependency react-markdown → unified → is-plain-obj exports only ES6, which I have to make some changes to my webpack config
2. The bug https://github.com/remarkjs/react-markdown/issues/460 which lives quite a long time makes it impossible to use HTML...
3. I tried to use remark-directive plugin, and... it is way too complex...

That's why I have to say goodbye to the world’s most popular Markdown parser and say Hi to the smallest CommonMark compliant markdown parser.

However, micromark has its own problems - the typings are NOT well-defined, I have to do quite a lot of diggings and hacking.

So far so good, cheers 🎉.

Usage 💥

Basic

import React from 'react';

import Markdown from '@alicloud/rc-markdown';

export default function MyMarkdown(): JSX.Element {
  return <Markdown {...{
    source: __YOUR_MARKDOWN_DOCUMENT_IN_STRING_FORMAT__
  }} />;
}

Use Directive

import React from 'react';

import Markdown, {
  MicromarkDirective,
  MarkdownExtensionDirectiveHtmlOptions
} from '@alicloud/rc-markdown';

// remember to make it static, do NOT put it inside render
const directiveOptions: MarkdownExtensionDirectiveHtmlOptions = {
  abbr(d: MicromarkDirective) {
    if (d.type !== 'textDirective') {
      return false;
    }
    
    this.tag('<abbr');
    
    if (d.attributes && 'title' in d.attributes) {
      this.tag(` title="${this.encode(d.attributes.title)}"`);
    }
    
    this.tag('>');
    this.raw(d.label || '');
    this.tag('</abbr>');
  }
};

export default function MyMarkdown(): JSX.Element {
  return <Markdown {...{
    source: __YOUR_MARKDOWN_DOCUMENT_IN_STRING_FORMAT__,
    plugins: {
      directive: directiveOptions
    }
  }} />;
}

Styles 🔥

This package ships with no styles at all.

Use @alicloud/console-base-rc-markdown you want to have a beautiful look (with CSS var), or maybe you can wrap with your own styling code.

Useful Links ✨

• Markdown
• CommonMark
• Learn Markdown in 16 Seconds
• Markdown Basic Syntax
• Markdown Extended Syntax
• micromark
• micromark-extension-gfm
• micromark-extension-directive
• mdast
• remark
• react-markdown