About

jui-markdown uses markdown-to-jsx and JoyUI(from MUI) to help you render MD/MDX files with JoyUI components.

This is an alternative to the mui-markdown for the JoyUI library initialized by this pull request.

User Guide

Installation

# with npm
npm i jui-markdown@latest

# with yarn
yarn add jui-markdown

Usage

The example below will render the h1 tag using JoyUI Typography component.

import React from 'react';
import { JuiMarkdown } from 'jui-markdown';
// You can also use
// import JuiMarkdown from 'jui-markdown';
// But the first approach is recommended.

const App = () => {
  return <JuiMarkdown>{`# Hello markdown!`}</JuiMarkdown>;
};

export default App;

Props

Props available for JuiMarkdown component:

| Name | Type | Default | Optional or Mandatory | | ----------------- | ----------------------- | ---------------- | --------------------- | | key | React.key | - | optional | | children | string | - | optional | | overrides | MarkdownToJSX.Overrides | defaultOverrides | optional | | options | MarkdownToJSX.Options | - | optional | | codeWrapperStyles | CSSProperties | - | optional | | prismTheme | PrismTheme | vsDark | optional | | Highlight | HighlightComponent | - | optional | | themes | HighlightThemes | - | optional | | hideLineNumbers | boolean | false | optional |

NOTE: You cannot use overrides and options at the same time.

overrides

You can optionally override a tag to use your component.

An example of override with a regular HTML tag:

JS and JSX:

import React from 'react';
import { JuiMarkdown, getOverrides } from 'jui-markdown';

const App = () => {
  return (
    <JuiMarkdown
      overrides={{
        ...getOverrides({}), // This will keep the other default overrides.
        h1: {
          component: 'p',
          props: {
            style: { color: 'red' },
          },
        },
      }}
    >
      {`# Hello markdown!`}
    </JuiMarkdown>
  );
};

export default App;

TS and TSX:

import React from 'react';
import { JuiMarkdown, getOverrides } from 'jui-markdown';

const App = () => {
  return (
    <JuiMarkdown
      overrides={{
        ...getOverrides(), // This will keep the other default overrides.
        h1: {
          component: 'p',
          props: {
            style: { color: 'red' },
          } as React.HTMLProps<HTMLParagraphElement>,
        },
      }}
    >
      {`# Hello markdown!`}
    </JuiMarkdown>
  );
};

export default App;

An example of override with your component:

JS and JSX:

import React from 'react';
import { JuiMarkdown, getOverrides } from 'jui-markdown';
import CustomTypography from './components/CustomTypography';

const App = () => {
  return (
    <JuiMarkdown
      overrides={{
        ...getOverrides(), // This will keep the other default overrides.
        h1: {
          component: CustomTypography,
          props: {
            // custom props
          },
        },
      }}
    >
      {`# Hello markdown!`}
    </JuiMarkdown>
  );
};

export default App;

TS and TSX:

import React from 'react';
import { JuiMarkdown, getOverrides } from 'jui-markdown';
import CustomTypography, {
  CustomTypographyProps,
} from './components/CustomTypography';

const App = () => {
  return (
    <JuiMarkdown
      overrides={{
        ...getOverrides(), // This will keep the other default overrides.
        h1: {
          component: CustomTypography,
          props: {
            // custom props
          } as CustomTypographyProps,
        },
      }}
    >
      {`# Hello markdown!`}
    </JuiMarkdown>
  );
};

export default App;

options

You can read about options in the markdown-to-jsx docs.

Note: If you want to override something and also need to set some options, add the overrides property in the options. Don't use overrides and options property together on the JuiMarkdown component.

codeWrapperStyles

You can pass your desired styles for the syntax highlighter component. These are the default styles:

  ...
  borderRadius: '0.5rem',
  padding: '0.5rem 0.75rem',
  overflow: 'auto',
  ...

Syntax Highlight

jui-markdown uses prism-react-renderer to highlight code blocks. As this is an optional dependencies, you need to install it if you want to have a syntax highlighter. So to highlight your code:

• First install prism-react-renderer

# with npm
npm i prism-react-renderer

# with yarn
yarn add prism-react-renderer

• Then pass the Highlight and the themes to the JuiMarkdown component

import React from 'react';
import { JuiMarkdown } from 'jui-markdown';
import { Highlight, themes } from 'prism-react-renderer';

const App = () => {
  return (
    <JuiMarkdown
      Highlight={Highlight}
      themes={themes}
      prismTheme={themes.github}
    >
      {`# Hello markdown!`}
    </JuiMarkdown>
  );
};

export default App;

With the prismTheme property you can change the highlight theme.

import React from 'react';
import { JuiMarkdown } from 'jui-markdown';
import { Highlight, themes } from 'prism-react-renderer';

const App = () => {
  return (
    <JuiMarkdown
      Highlight={Highlight}
      themes={themes}
      prismTheme={themes.github}
    >
      {`# Hello markdown!`}
    </JuiMarkdown>
  );
};

export default App;

Also to disable the line numbers in the code block you can use the hideLineNumbers.

import React from 'react';
import { JuiMarkdown } from 'jui-markdown';
import { Highlight, themes } from 'prism-react-renderer';

const App = () => {
  return (
    <JuiMarkdown
      Highlight={Highlight}
      themes={themes}
      prismTheme={themes.github}
      hideLineNumbers
    >
      {`# Hello markdown!`}
    </JuiMarkdown>
  );
};

export default App;

When you use overrides, you can have the syntax highlight by passing the Highlight, themes, and themes.github (or your favorite one) to the getOverrides function.

import React from 'react';
import { JuiMarkdown, getOverrides } from 'jui-markdown';
import { Highlight, themes } from 'prism-react-renderer';

const App = () => {
  return (
    <JuiMarkdown
      overrides={{
        ...getOverrides({ Highlight, themes, theme: themes.github }), // This will keep the other default overrides.
        h1: {
          component: 'p',
          props: {
            style: { color: 'red' },
          },
        },
      }}
    >
      {`# Hello markdown!`}
    </JuiMarkdown>
  );
};

export default App;