remarkjs / react-markdown

react-markdown [![Build][badge-build-image]][badge-build-url] [![Coverage][badge-coverage-image]][badge-coverage-url] [![Downloads][badge-downloads-image]][badge-downloads-url] [![Size][badge-size-image]][badge-size-url] React component to render markdown. Feature highlights • [x] **[safe][section-security] by default** (no or XSS attacks) • [x] **[components][section-components]** (pass your own component to use instead of for ) • [x] **[plugins][section-plugins]** (many plugins you can pick and choose from) • [x] **[compliant][section-syntax]** (100% to CommonMark, 100% to GFM with a plugin) Contents • What is this? • When should I use this? • Install • Use • API • * • * • * • * • * • Examples • Use a plugin • Use a plugin with options • Use custom components (syntax highlight) • Use remark and rehype plugins (math) • Plugins • Syntax • Compatibility • Architecture • Appendix A: HTML in markdown • Appendix B: Components • Appendix C: line endings in markdown (and JSX) • Security • Related • Contribute • License What is this? This package is a [React][] component that can be given a string of markdown that it’ll safely render to React elements. You can pass plugins to change how markdown is transformed and pass components that will be used instead of normal HTML elements. • to learn markdown, see this [cheatsheet and tutorial][commonmark-help] • to try out , see [our demo][github-io-react-markdown] When should I use this? There are other ways to use markdown in React out there so why use this one? The three main reasons are that they often rely on , have bugs with how they handle markdown, or don’t let you swap elements for components. builds a virtual DOM, so React only replaces what changed, from a syntax tree. That’s supported because we use [unified][github-unified], specifically [remark][github-remark] for markdown and [rehype][github-rehype] for HTML, which are popular tools to transform content with plugins. This package focusses on making it easy for beginners to safely use markdown in React. When you’re familiar with unified, you can use a modern hooks based alternative [ ][github-react-remark] or [ ][github-rehype-react] manually. If you instead want to use JavaScript and JSX *inside* markdown files, use [MDX][github-mdx]. Install This package is [ESM only][esm]. In Node.js (version 16+), install with [npm][npm-install]: In Deno with [ ][esmsh]: In browsers with [ ][esmsh]: Use A basic hello world: Show equivalent JSX Here is an example that shows how to use a plugin ([ ][github-remark-gfm], which adds support for footnotes, strikethrough, tables, tasklists and URLs directly): Show equivalent JSX API This package exports the identifiers [ ][api-markdown-async], [ ][api-markdown-hooks], and [ ][api-default-url-transform]. The default export is [ ][api-markdown]. It also exports the additional [TypeScript][] types [ ][api-allow-element], [ ][api-components], [ ][api-extra-props], [ ][api-hooks-options], [ ][api-options], and [ ][api-url-transform]. Component to render markdown. This is a synchronous component. When using async plugins, see [ ][api-markdown-async] or [ ][api-markdown-hooks]. Parameters • ([ ][api-options]) — props Returns React element ( ). Component to render markdown with support for async plugins through async/await. Components returning promises are supported on the server. For async support on the client, see [ ][api-markdown-hooks]. Parameters • ([ ][api-options]) — props Returns Promise to a React element ( ). Component to render markdown with support for async plugins through hooks. This uses and hooks. Hooks run on the client and do not immediately render something. For async support on the server, see [ ][api-markdown-async]. Parameters • ([ ][api-options]) — props Returns React node ( ). Make a URL safe. This follows how GitHub works. It allows the protocols , , , , , and , and URLs relative to the current protocol (such as ). Parameters • ( ) — URL Returns Safe URL ( ). Filter elements (TypeScript type). Parameters • ([ from ][github-hast-element]) — element to check • ( ) — index of in • ([ from ][github-hast-nodes]) — parent of Returns Whether to allow ( , optional). Map tag names to components (TypeScript type). Type Extra fields we pass to components (TypeScript type). Fields • ([ from ][github-hast-element], optional) — original node Configuration for [ ][api-markdown-hooks] (TypeScript type); extends the regular [ ][api-options] with a prop. Extends [ ][api-options]. Fields • ( , optional) — content to render while the processor processing the markdown Configuration (TypeScript type). Fields • ([ ][api-allow-element], optional) — filter elements; / is used first • ( , default: all tag names) — tag names to allow; cannot combine w/ • ( , optional) — markdown • ([ ][api-components], optional) — map tag names to components • ( , default: ) — tag names to disallow; cannot combine w/ • ( , optional) — list of [rehype plugins][github-rehype-plugins] to use • ( , optional) — list of [remark plugins][github-remark-plugins] to use • ([ from ][github-remark-rehype-options], optional) — options to pass through to • ( , default: ) — ignore HTML in markdown completely • ( , default: ) — extract (unwrap) what’s in disallowed elements; normally when say is not allowed, it and it’s children are dropped, with the element itself is replaced by its children • ([ ][api-url-transform], default: [ ][api-default-url-transform]) — change URLs Transform URLs (TypeScript type). Parameters • ( ) — URL • ( , example: ) — property name • ([ from ][github-hast-element]) — element to check Returns Transformed URL ( , optional). Examples Use a plugin This example shows how to use a remark plugin. In this case, [ ][github-remark-gfm], which adds support for strikethrough, tables, tasklists and URLs directly: Show equivalent JSX Use a plugin with options This example shows how…