markdown-to-jsx

What is markdown-to-jsx?

The markdown-to-jsx package is an npm package that allows you to parse and render Markdown content as React components. It is lightweight and customizable, making it a good choice for projects that need to convert Markdown to JSX without heavy dependencies.

What are markdown-to-jsx's main functionalities?

Basic Markdown Parsing

This feature allows you to render basic Markdown text as React components. The example code shows how to import the Markdown component from the package and use it to render a simple Markdown string.

import Markdown from 'markdown-to-jsx';

const markdownInput = '# Hello World!';

function App() {
  return <Markdown>{markdownInput}</Markdown>;
}

Custom Components

This feature allows you to use custom components to render specific parts of the Markdown content. In the example, a custom anchor component is used to replace the default rendering of links.

import Markdown from 'markdown-to-jsx';
import MyCustomComponent from './MyCustomComponent';

const markdownInput = '[Click me](#custom)';

const options = {
  overrides: {
    a: {
      component: MyCustomComponent,
      props: {
        className: 'my-custom-class'
      }
    }
  }
};

function App() {
  return <Markdown options={options}>{markdownInput}</Markdown>;
}

Markdown Options

This feature allows you to customize the parsing and rendering behavior of the Markdown content. The example demonstrates how to use options to modify the default behavior, such as forcing block-level rendering or customizing the slugify function.

import Markdown from 'markdown-to-jsx';

const markdownInput = 'Hello, *world*!';

const options = {
  forceBlock: true,
  forceInline: false,
  slugify: (text) => text.toLowerCase().replace(/\s/g, '-')
};

function App() {
  return <Markdown options={options}>{markdownInput}</Markdown>;
}

Other packages similar to markdown-to-jsx

react-markdown

react-markdown is a popular Markdown renderer for React that uses remark to parse Markdown. It is similar to markdown-to-jsx but offers a more extensive plugin system, which allows for more customization and extensibility at the cost of a larger bundle size.

marked

marked is a low-level Markdown compiler for parsing Markdown without caching or blocking for long periods of time. It is not specifically designed for React like markdown-to-jsx, but it can be used in a React project with additional setup. It is known for its speed and extensibility.

remarkable

remarkable is another Markdown parser that can be configured extensively with plugins. It is not React-specific and provides a full-featured Markdown to HTML converter. Compared to markdown-to-jsx, it might require additional integration steps for use within React applications.

README

markdown to jsx converter

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.

Uses remark under the hood to parse markdown into a consistent AST format.

Requires React >= 0.14.

Usage

import converter from 'markdown-to-jsx';
import React from 'react';
import {render} from 'react-dom';

render(converter('# Hello world!'), document.body);

remark options can be passed as the second argument:

converter('* abc\n* def\n* ghi', {bullet: '*'});

Footnotes are enabled by default as of markdown-to-jsx@2.0.0.

Overriding tags and adding props

As of markdown-to-jsx@2.0.0, 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.

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.

converter('Hello there!', {}, {
    p: {
        component: MyParagraph,
        props: {
            className: 'foo'
        },
    }
});

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
• img: title, alt, src
• ol: start
• td: style
• th: style

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

MIT