mui-markdown

Support this project by giving it a star on GitHub.

About

mui-markdown uses markdown-to-jsx and MUI(formerly material-ui) to help you render MD/MDX files with MUI components.

User Guide

Installation

# with npm
npm i mui-markdown@latest

# with yarn
yarn add mui-markdown

Usage

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

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

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

export default App;

Props

Props available for MuiMarkdown 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 { MuiMarkdown, getOverrides } from 'mui-markdown';

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

export default App;

TS and TSX:

import React from 'react';
import { MuiMarkdown, getOverrides } from 'mui-markdown';

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

export default App;

An example of override with your component:

JS and JSX:

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

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

export default App;

TS and TSX:

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

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

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 MuiMarkdown 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

mui-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 MuiMarkdown component

import React from 'react';
import { MuiMarkdown } from 'mui-markdown';
import { Highlight, themes } from 'prism-react-renderer';

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

export default App;

With the prismTheme property you can change the highlight theme.

import React from 'react';
import { MuiMarkdown } from 'mui-markdown';
import { Highlight, themes } from 'prism-react-renderer';

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

export default App;

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

import React from 'react';
import { MuiMarkdown } from 'mui-markdown';
import { Highlight, themes } from 'prism-react-renderer';

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

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 { MuiMarkdown, getOverrides } from 'mui-markdown';
import { Highlight, themes } from 'prism-react-renderer';

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

export default App;

NextJS

Use with useMDXComponents

To add mui-markdown to useMDXComponents you can either import defaultMdxComponents or use getMdxComponents if you need to override defaults.

import type { MDXComponents } from 'mdx/types';

import { defaultMdxComponents, getMdxComponents } from 'mui-markdown';

// You can use the getMdxComponents(options) to override defaults!
// const mdxComponents = getMdxComponents();

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // ...mdxComponents,
    ...defaultMdxComponents,
    ...components,
  };
}

Backers