{"id":13998438,"url":"https://github.com/HPouyanmehr/mui-markdown","last_synced_at":"2025-07-23T06:31:39.778Z","repository":{"id":44406532,"uuid":"450506945","full_name":"HPouyanmehr/mui-markdown","owner":"HPouyanmehr","description":"mui-markdown helps you render MD/MDX files with MUI components.","archived":false,"fork":false,"pushed_at":"2024-11-07T15:19:05.000Z","size":2423,"stargazers_count":70,"open_issues_count":1,"forks_count":18,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-15T22:55:46.224Z","etag":null,"topics":["markdown","mdx","react"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HPouyanmehr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-21T13:42:24.000Z","updated_at":"2024-11-07T15:19:14.000Z","dependencies_parsed_at":"2023-12-18T21:58:42.311Z","dependency_job_id":"76cf0509-d599-4d5c-95ae-d7686abe0ca3","html_url":"https://github.com/HPouyanmehr/mui-markdown","commit_stats":{"total_commits":38,"total_committers":3,"mean_commits":"12.666666666666666","dds":"0.13157894736842102","last_synced_commit":"4b86e6c9b940548430f7ff6cab0e453222c21421"},"previous_names":["hajhosein/mui-markdown"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HPouyanmehr%2Fmui-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HPouyanmehr%2Fmui-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HPouyanmehr%2Fmui-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HPouyanmehr%2Fmui-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HPouyanmehr","download_url":"https://codeload.github.com/HPouyanmehr/mui-markdown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227245175,"owners_count":17753239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","mdx","react"],"created_at":"2024-08-09T19:01:40.387Z","updated_at":"2025-07-23T06:31:39.721Z","avatar_url":"https://github.com/HPouyanmehr.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"![Mui Markdown Cover](./.github/assets/mui-markdown.webp)\n\n# MUI-Markdown\n\n## About\n\n`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.\n\nUsing `mui-markdown`:\n\n- Markdown components will adapt to theme automatically\n- Optional Syntax Highlight Support using `prism-react-renderer`\n- Optional Diagrams Support using `mermaid`\n\n## Table of Contents\n\n- [User Guide](#user-guide)\n  - [Installation](#installation)\n  - [Usage](#usage)\n  - [Props](#props)\n  - [Overrides](#overrides)\n  - [Options](#options)\n  - [Code Wrapper Styles](#codewrapperstyles)\n  - [Syntax Highlight](#syntax-highlight)\n- [Diagram Support](#diagram-support)\n- [NextJS](#nextjs)\n  - [Use with `useMDXComponents`](#use-with-usemdxcomponents)\n\n## User Guide\n\n### Installation\n\n```bash\n# with npm\nnpm i mui-markdown@latest\n\n# with yarn\nyarn add mui-markdown\n```\n\n### Usage\n\nThe example below will render the `h1` tag using MUI `Typography` component.\n\n```js\nimport React from 'react';\nimport { MuiMarkdown } from 'mui-markdown';\n// You can also use\n// import MuiMarkdown from 'mui-markdown';\n// But the first approach is recommended.\n\nconst App = () =\u003e {\n  return \u003cMuiMarkdown\u003e{`# Hello markdown!`}\u003c/MuiMarkdown\u003e;\n};\n\nexport default App;\n```\n\n### Props\n\nProps available for `MuiMarkdown` component:\n\n| Name              | Type                    | Default          | Optional or Mandatory |\n| ----------------- | ----------------------- | ---------------- | --------------------- |\n| key               | React.key               | -                | **optional**          |\n| children          | string                  | -                | **optional**          |\n| overrides*        | MarkdownToJSX.Overrides | defaultOverrides | **optional**          |\n| options*          | MarkdownToJSX.Options   | -                | **optional**          |\n| codeWrapperStyles | CSSProperties           | -                | **optional**          |\n| prismTheme        | PrismTheme              | vsDark           | **optional**          |\n| Highlight         | HighlightComponent      | -                | **optional**          |\n| themes            | HighlightThemes         | -                | **optional**          |\n| hideLineNumbers   | boolean                 | false            | **optional**          |\n| enableMermaid     | boolean                 | false            | **optional**          |\n| mermaidConfig     | MermaidConfig           | -                | **optional**          |\n| Diagram*          | DiagramComponent        | -                | **optional**          |\n\n**NOTE:** You cannot use overrides and options at the same time.\n**NOTE:** You must provide the `Diagram` component if you've enabled the mermaid.\n\n### overrides\n\nYou can optionally override a tag to use your component.\n\n**An example of override with a regular HTML tag:**\n\nJS and JSX:\n\n```jsx\nimport React from 'react';\nimport { MuiMarkdown, defaultOverrides } from 'mui-markdown';\n\nconst App = () =\u003e {\n  return (\n    \u003cMuiMarkdown\n      overrides={{\n        ...defaultOverrides, // This will keep the other default overrides.\n        h1: {\n          component: 'p',\n          props: {\n            style: { color: 'red' },\n          },\n        },\n      }}\n    \u003e\n      {`# Hello markdown!`}\n    \u003c/MuiMarkdown\u003e\n  );\n};\n\nexport default App;\n```\n\nTS and TSX:\n\n```tsx\nimport React from 'react';\nimport { MuiMarkdown, defaultOverrides } from 'mui-markdown';\n\nconst App = () =\u003e {\n  return (\n    \u003cMuiMarkdown\n      overrides={{\n        ...defaultOverrides, // This will keep the other default overrides.\n        h1: {\n          component: 'p',\n          props: {\n            style: { color: 'red' },\n          } as React.HTMLProps\u003cHTMLParagraphElement\u003e,\n        },\n      }}\n    \u003e\n      {`# Hello markdown!`}\n    \u003c/MuiMarkdown\u003e\n  );\n};\n\nexport default App;\n```\n\n**An example of override with your component:**\n\nJS and JSX:\n\n```jsx\nimport React from 'react';\nimport { MuiMarkdown, defaultOverrides } from 'mui-markdown';\nimport CustomTypography from './components/CustomTypography';\n\nconst App = () =\u003e {\n  return (\n    \u003cMuiMarkdown\n      overrides={{\n        ...defaultOverrides, // This will keep the other default overrides.\n        h1: {\n          component: CustomTypography,\n          props: {\n            // custom props\n          },\n        },\n      }}\n    \u003e\n      {`# Hello markdown!`}\n    \u003c/MuiMarkdown\u003e\n  );\n};\n\nexport default App;\n```\n\nTS and TSX:\n\n```tsx\nimport React from 'react';\nimport { MuiMarkdown, defaultOverrides } from 'mui-markdown';\nimport CustomTypography, {\n  CustomTypographyProps,\n} from './components/CustomTypography';\n\nconst App = () =\u003e {\n  return (\n    \u003cMuiMarkdown\n      overrides={{\n        ...defaultOverrides, // This will keep the other default overrides.\n        h1: {\n          component: CustomTypography,\n          props: {\n            // custom props\n          } as CustomTypographyProps,\n        },\n      }}\n    \u003e\n      {`# Hello markdown!`}\n    \u003c/MuiMarkdown\u003e\n  );\n};\n\nexport default App;\n```\n\n### options\n\nYou can read about options in the [markdown-to-jsx](https://www.npmjs.com/package/markdown-to-jsx#parsing-options) docs.\n\n**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.\n\n### codeWrapperStyles\n\nYou can pass your desired styles for the syntax highlighter component. These are the default styles:\n\n```tsx\n  ...\n  borderRadius: '0.5rem',\n  padding: '0.5rem 0.75rem',\n  overflow: 'auto',\n  ...\n```\n\n### Syntax Highlight\n\n`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:\n\n- First install `prism-react-renderer`\n\n```bash\n# with npm\nnpm i prism-react-renderer\n\n# with yarn\nyarn add prism-react-renderer\n```\n\n- Then pass the `Highlight` and the `themes` to the `MuiMarkdown` component\n\n```tsx\nimport React from 'react';\nimport { MuiMarkdown } from 'mui-markdown';\nimport { Highlight, themes } from 'prism-react-renderer';\n\nconst App = () =\u003e {\n  return (\n    \u003cMuiMarkdown\n      Highlight={Highlight}\n      themes={themes}\n      prismTheme={themes.github}\n    \u003e\n      {`# Hello markdown!`}\n    \u003c/MuiMarkdown\u003e\n  );\n};\n\nexport default App;\n```\n\nWith the `prismTheme` property you can change the highlight theme.\n\n```tsx\nimport React from 'react';\nimport { MuiMarkdown } from 'mui-markdown';\nimport { Highlight, themes } from 'prism-react-renderer';\n\nconst App = () =\u003e {\n  return (\n    \u003cMuiMarkdown\n      Highlight={Highlight}\n      themes={themes}\n      prismTheme={themes.github}\n    \u003e\n      {`# Hello markdown!`}\n    \u003c/MuiMarkdown\u003e\n  );\n};\n\nexport default App;\n```\n\nAlso to disable the line numbers in the code block you can use the `hideLineNumbers`.\n\n```tsx\nimport React from 'react';\nimport { MuiMarkdown } from 'mui-markdown';\nimport { Highlight, themes } from 'prism-react-renderer';\n\nconst App = () =\u003e {\n  return (\n    \u003cMuiMarkdown\n      Highlight={Highlight}\n      themes={themes}\n      prismTheme={themes.github}\n      hideLineNumbers\n    \u003e\n      {`# Hello markdown!`}\n    \u003c/MuiMarkdown\u003e\n  );\n};\n\nexport default App;\n```\n\nWhen 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.\n\n```tsx\nimport React from 'react';\nimport { MuiMarkdown, getOverrides } from 'mui-markdown';\nimport { Highlight, themes } from 'prism-react-renderer';\n\nconst App = () =\u003e {\n  return (\n    \u003cMuiMarkdown\n      overrides={{\n        ...getOverrides({ Highlight, themes, theme: themes.github }), // This will keep the other default overrides.\n        h1: {\n          component: 'p',\n          props: {\n            style: { color: 'red' },\n          },\n        },\n      }}\n    \u003e\n      {`# Hello markdown!`}\n    \u003c/MuiMarkdown\u003e\n  );\n};\n\nexport default App;\n```\n\n## Diagram Support\n\n`mui-markdown` uses [`mermaid`](https://github.com/mermaid-js/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.\n\nThe `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) =\u003e JSX.Element`. Props type is available under `mui-markdown` and `mui-markdown/client`.\n\n```tsx\nimport React from 'react';\nimport { MuiMarkdown, getOverrides } from 'mui-markdown';\nimport { Diagram } from 'mui-markdown/client'; // This component will handle mermaid init and content load\nimport { Highlight, themes } from 'prism-react-renderer';\n\nconst App = () =\u003e {\n  return (\n    \u003cMuiMarkdown\n      enableMermaid\n      mermaidConfig={{startOnLoad: true}}\n      DiagramComponent={Diagram}\n    \u003e\n      {/* Markdown content */}\n    \u003c/MuiMarkdown\u003e\n  );\n};\n\nexport default App;\n```\n\n## NextJS\n\n### Use with `useMDXComponents`\n\nTo add `mui-markdown` to `useMDXComponents` you can either import `defaultMdxComponents` or use `getMdxComponents` if you need to override defaults.\n\n```ts\nimport type { MDXComponents } from 'mdx/types';\n\nimport { defaultMdxComponents, getMdxComponents } from 'mui-markdown';\n\n// You can use the getMdxComponents(options) to override defaults!\n// const mdxComponents = getMdxComponents();\n\nexport function useMDXComponents(components: MDXComponents): MDXComponents {\n  return {\n    // ...mdxComponents,\n    ...defaultMdxComponents,\n    ...components,\n  };\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHPouyanmehr%2Fmui-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHPouyanmehr%2Fmui-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHPouyanmehr%2Fmui-markdown/lists"}