mui-markdown uses markdown-to-jsx and MUI(formerly material-ui) to help you render MD/MDX files with MUI components.
npm install mui-markdownSupport this project by giving it a star on GitHub.
mui-markdown uses markdown-to-jsx and MUI(formerly material-ui) to help you render MD/MDX files with MUI components.
Using mui-markdown:
- Markdown components will adapt to theme automatically
- Optional Syntax Highlight Support using prism-react-renderer
- Optional Diagrams Support using mermaid
- User Guide
- Installation
- Usage
- Props
- Overrides
- Options
- CodeWrapperStyles
- Syntax Highlight
- Enhanced Code Block Features
- Diagram Support
- NextJS
- Use with useMDXComponents
``bashwith npm
npm i mui-markdown@latest
$3
The example below will render the
h1 tag using MUI Typography component.`js
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 {
# Hello markdown!};
};export default App;
`$3
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 |
| customTableScrollbar | boolean | false | optional |
| hideLineNumbers | boolean | false | optional |
| name | string | - | optional |
| copiable | boolean | false | optional |
| CopyComponent | ComponentType | - | optional |
| copiedLabel | string | 'Copied!' | optional |
| copyLabel | string | 'Copy code' | optional |
| copyIcon | ReactNode | - | optional |
| copiedIcon | ReactNode | - | optional |
| copyButtonSx | SxProps | - | optional |
| showFileIcon | boolean | true | optional |
| fileIcon | ReactNode | - | optional |
| FileNameComponent | ComponentType | Typography | optional |
| fileNameSx | SxProps | - | optional |
| fileNameWrapperSx | SxProps | - | optional |
| useHighlightThemeBackground | boolean | false | optional |
| highlightColor | string | 'info.main' | optional |
| removedColor | string | 'error.main' | optional |
| insertedColor | string | 'success.main' | optional |
| enableMermaid | boolean | false | optional |
| mermaidConfig | MermaidConfig | - | optional |
| Diagram\* | DiagramComponent | - | optional |
NOTE: You cannot use overrides and options at the same time
NOTE: Using
customTableScrollbar option convert table to a client side component.NOTE: You must provide the
Diagram component if you've enabled the mermaid.$3
You can optionally override a tag to use your component.
An example of override with a regular HTML tag:
JS and JSX:
`jsx
import React from 'react';
import { MuiMarkdown, defaultOverrides } from 'mui-markdown';const App = () => {
return (
overrides={{
...defaultOverrides, // This will keep the other default overrides.
h1: {
component: 'p',
props: {
style: { color: 'red' },
},
},
}}
>
{
# Hello markdown!}
);
};export default App;
`TS and TSX:
`tsx
import React from 'react';
import { MuiMarkdown, defaultOverrides } from 'mui-markdown';const App = () => {
return (
overrides={{
...defaultOverrides, // This will keep the other default overrides.
h1: {
component: 'p',
props: {
style: { color: 'red' },
} as React.HTMLProps,
},
}}
>
{
# Hello markdown!}
);
};export default App;
`An example of override with your component:
JS and JSX:
`jsx
import React from 'react';
import { MuiMarkdown, defaultOverrides } from 'mui-markdown';
import CustomTypography from './components/CustomTypography';const App = () => {
return (
overrides={{
...defaultOverrides, // This will keep the other default overrides.
h1: {
component: CustomTypography,
props: {
// custom props
},
},
}}
>
{
# Hello markdown!}
);
};export default App;
`TS and TSX:
`tsx
import React from 'react';
import { MuiMarkdown, defaultOverrides } from 'mui-markdown';
import CustomTypography, {
CustomTypographyProps,
} from './components/CustomTypography';const App = () => {
return (
overrides={{
...defaultOverrides, // This will keep the other default overrides.
h1: {
component: CustomTypography,
props: {
// custom props
} as CustomTypographyProps,
},
}}
>
{
# Hello markdown!}
);
};export default App;
`$3
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.$3
You can pass your desired styles for the syntax highlighter component. These are the default styles:
`tsx
...
borderRadius: '0.5rem',
padding: '0.5rem 0.75rem',
overflow: 'auto',
...
`$3
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`bash
with npm
npm i prism-react-rendererwith yarn
yarn add prism-react-renderer
`- Then pass the
Highlight and the themes to the MuiMarkdown component`tsx
import React from 'react';
import { MuiMarkdown } from 'mui-markdown';
import { Highlight, themes } from 'prism-react-renderer';const App = () => {
return (
Highlight={Highlight}
themes={themes}
prismTheme={themes.github}
>
{
# Hello markdown!}
);
};export default App;
`With the
prismTheme property you can change the highlight theme.`tsx
import React from 'react';
import { MuiMarkdown } from 'mui-markdown';
import { Highlight, themes } from 'prism-react-renderer';const App = () => {
return (
Highlight={Highlight}
themes={themes}
prismTheme={themes.github}
>
{
# Hello markdown!}
);
};export default App;
`Also to disable the line numbers in the code block you can use the
hideLineNumbers.`tsx
import React from 'react';
import { MuiMarkdown } from 'mui-markdown';
import { Highlight, themes } from 'prism-react-renderer';const App = () => {
return (
Highlight={Highlight}
themes={themes}
prismTheme={themes.github}
hideLineNumbers
>
{
# Hello markdown!}
);
};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.`tsx
import React from 'react';
import { MuiMarkdown, getOverrides } from 'mui-markdown';
import { Highlight, themes } from 'prism-react-renderer';const App = () => {
return (
overrides={{
...getOverrides({ Highlight, themes, theme: themes.github }), // This will keep the other default overrides.
h1: {
component: 'p',
props: {
style: { color: 'red' },
},
},
}}
>
{
# Hello markdown!}
);
};export default App;
`$3
mui-markdown supports advanced code block features for better documentation and code presentation.#### Available Features
| Feature | Markdown Attribute | Global Prop | Description |
| ----------------- | --------------------- | ------------------------ | --------------------------------------------------------- |
| Line Highlighting |
highlighted="1,3-5" | - | Highlights specific lines with blue background |
| Removed Lines | removed="2,4" | - | Shows deletion lines with red background and - prefix |
| Inserted Lines | inserted="3,5-7" | - | Shows addition lines with green background and + prefix |
| File Name | name="path/file.ts" | name="path/file.ts" | Displays file name/path above code block |
| Copy Button | copiable | copiable={true} | Adds a copy-to-clipboard button |
| Hide Line Numbers | hideLineNumbers | hideLineNumbers={true} | Toggles line number visibility |#### Usage Examples
Highlighting Important Lines:
``markdown
`tsx highlighted="2,4-6"
function Button({ children }) {
const [clicked, setClicked] = useState(false); const handleClick = () => {
setClicked(true);
};
return ;
}
`
``Showing Code Diffs:
``markdown
`tsx removed="2" inserted="3"
export async function getUser(id) {
const url = /api/user/${id};
const url = /api/v2/users/${id};
return fetch(url).then((r) => r.json());
}
`
``Hiding Line Numbers Per Code Block:
``markdown
`tsx hideLineNumbers
export function Header({ title }) {
return (
{title}
);
}
`
``File Name with Copy Button:
``markdown
`tsx name="components/Header.tsx" copiable
export function Header({ title }) {
return (
{title}
);
}
`
``Combined Features:
``markdown
`tsx name="src/utils/validator.ts" highlighted="4-6" removed="7" inserted="8" copiable hideLineNumbers
export function validateEmail(email: string): boolean {
const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; if (!email) {
return false;
}
const trimmedEmail = email.trimEnd();
const trimmedEmail = email.trim();
return regex.test(trimmedEmail);
}
`
``#### Global Configuration
You can set defaults for all code blocks using
getOverrides:`tsx
import { MuiMarkdown, getOverrides } from 'mui-markdown';
import { Highlight, themes } from 'prism-react-renderer';const overrides = getOverrides({
Highlight,
themes,
copiable: true, // All code blocks have copy button
hideLineNumbers: false, // Show line numbers by default
copiedLabel: 'Copied!', // Customize copy button labels
copyLabel: 'Copy',
});
function App() {
return {markdownContent} ;
}
`#### Per-Block Overrides
Markdown attributes override global settings, allowing you to customize individual code blocks:
``markdown
`tsx hideLineNumbers copiable name="config.ts"
export const config = {
apiUrl: process.env.API_URL,
timeout: 5000,
};
`
``#### Line Range Syntax
The line range parser supports flexible syntax:
- Single lines:
"1" or "1,2,3"
- Ranges: "1-5" or "1-5,8-10"
- Mixed: "1,3-5,7,9-12"#### Customization
All visual elements can be customized using MUI theming:
Custom Colors:
`tsx
const overrides = getOverrides({
Highlight,
themes,
highlightColor: 'primary.main', // Use theme colors
removedColor: 'error.dark',
insertedColor: 'success.light',
});
`Custom Copy Button Icons:
`tsx
import ContentCopyIcon from '@mui/icons-material/ContentCopy';
import CheckIcon from '@mui/icons-material/Check';const overrides = getOverrides({
Highlight,
themes,
copyIcon: ,
copiedIcon: ,
copyButtonSx: { top: 16, right: 16 }, // Custom positioning
});
`Custom Copy Component:
For complete control over the copy button, provide your own component:
`tsx
import { CopyComponentProps } from 'mui-markdown';
import { IconButton } from '@mui/material';const CustomCopyButton = ({ handleCopy, code }: CopyComponentProps) => {
return (
onClick={handleCopy}
sx={{ position: 'absolute', top: 8, right: 8 }}
>
Copy {code.split('\n').length} lines
);
};
const overrides = getOverrides({
Highlight,
themes,
CopyComponent: CustomCopyButton,
});
`Custom File Name Display:
`tsx
import FolderIcon from '@mui/icons-material/Folder';const overrides = getOverrides({
Highlight,
themes,
showFileIcon: true, // Show/hide icon
fileIcon: , // Custom icon
FileNameComponent: CustomTypography, // Custom component
fileNameSx: { fontWeight: 'bold' }, // Custom text styles
fileNameWrapperSx: { backgroundColor: 'primary.light', px: 3 }, // Custom wrapper styles
useHighlightThemeBackground: true, // Use prism theme background for file name wrapper
});
`Diagram Support
mui-markdown uses mermaid as its diagramming and charting tool, to enable that, first make sure you have the mermaid installed. By passing the enableMermaid key you'll be able to have diagram support in your markdowns, just make sure you've provided the Diagram component as well. Also, using the mermaidConfigs you can configure it as you like.The
Diagram component is a client-side component, You can create your desired one for that purpose if needed, just make sure the custom component satisfying the following type: (props: DiagramProps) => JSX.Element. Props type is available under mui-markdown and mui-markdown/client.`tsx
import React from 'react';
import { MuiMarkdown, getOverrides } from 'mui-markdown';
import { Diagram } from 'mui-markdown/client'; // This component will handle mermaid init and content load
import { Highlight, themes } from 'prism-react-renderer';const App = () => {
return (
enableMermaid
mermaidConfig={{ startOnLoad: true }}
DiagramComponent={Diagram}
>
{/ Markdown content /}
);
};
export default App;
`NextJS
$3
To add
mui-markdown to useMDXComponents you can either import defaultMdxComponents or use getMdxComponents if you need to override defaults.`ts
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,
};
}
``