Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hpouyanmehr/mui-markdown
mui-markdown helps you render MD/MDX files with MUI components.
https://github.com/hpouyanmehr/mui-markdown
markdown mdx react
Last synced: 4 days ago
JSON representation
mui-markdown helps you render MD/MDX files with MUI components.
- Host: GitHub
- URL: https://github.com/hpouyanmehr/mui-markdown
- Owner: HPouyanmehr
- Created: 2022-01-21T13:42:24.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-12-20T20:50:31.000Z (26 days ago)
- Last Synced: 2025-01-12T07:06:30.043Z (4 days ago)
- Topics: markdown, mdx, react
- Language: TypeScript
- Homepage:
- Size: 2.53 MB
- Stars: 74
- Watchers: 2
- Forks: 18
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## About
`mui-markdown` uses [markdown-to-jsx](https://github.com/probablyup/markdown-to-jsx) and [MUI(formerly material-ui)](https://github.com/mui-org/material-ui) to help you render MD/MDX files with MUI components.
## User Guide
### Installation
```bash
# 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.
```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;
```
### 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:
```jsx
import React from 'react';
import { MuiMarkdown, getOverrides } from 'mui-markdown';
const App = () => {
return (
{`# Hello markdown!`}
);
};
export default App;
```
TS and TSX:
```tsx
import React from 'react';
import { MuiMarkdown, getOverrides } from 'mui-markdown';
const App = () => {
return (
,
},
}}
>
{`# Hello markdown!`}
);
};
export default App;
```
**An example of override with your component:**
JS and JSX:
```jsx
import React from 'react';
import { MuiMarkdown, getOverrides } from 'mui-markdown';
import CustomTypography from './components/CustomTypography';
const App = () => {
return (
{`# Hello markdown!`}
);
};
export default App;
```
TS and TSX:
```tsx
import React from 'react';
import { MuiMarkdown, getOverrides } from 'mui-markdown';
import CustomTypography, {
CustomTypographyProps,
} from './components/CustomTypography';
const App = () => {
return (
{`# Hello markdown!`}
);
};
export default App;
```
### options
You can read about options in the [markdown-to-jsx](https://www.npmjs.com/package/markdown-to-jsx#parsing-options) 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:
```tsx
...
borderRadius: '0.5rem',
padding: '0.5rem 0.75rem',
overflow: 'auto',
...
```
### Syntax Highlight
`mui-markdown` uses [prism-react-renderer](https://github.com/FormidableLabs/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-renderer
# with 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 (
{`# 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 (
{`# 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 (
{`# 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 (
{`# Hello markdown!`}
);
};
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.
```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,
};
}
```
## Backers
