<>
  <p>
    A paragraph with <em>emphasis</em> and <strong>strong importance</strong>.
  </p>
  <blockquote>
    <p>
      A block quote with <del>strikethrough</del> and a URL:{' '}
      <a href="https://reactjs.org">https://reactjs.org</a>.
    </p>
  </blockquote>
  <ul className="contains-task-list">
    <li>Lists</li>
    <li className="task-list-item">
      <input type="checkbox" disabled /> todo
    </li>
    <li className="task-list-item">
      <input type="checkbox" disabled checked /> done
    </li>
  </ul>
  <p>A table:</p>
  <table>
    <thead>
      <tr>
        <th>a</th>
        <th>b</th>
      </tr>
    </thead>
  </table>
</>

<p>
  This ~is not~ strikethrough, but <del>this is</del>!
</p>

<>
  <p>Here is some JavaScript code:</p>
  <pre>
    <SyntaxHighlighter language="js" style={dark} PreTag="div" children="console.log('It works!')" />
  </pre>
</>

<p>
  The lift coefficient (
  <span className="katex">
    <span className="katex-mathml">
      <math xmlns="http://www.w3.org/1998/Math/MathML">{/* … */}</math>
    </span>
    <span className="katex-html" aria-hidden="true">
      {/* … */}
    </span>
  </span>
  ) is a dimensionless coefficient.
</p>

插件

我们使用 unified，特别是 remark 用于 Markdown 和 rehype 用于 HTML， 这些都是通过插件转换内容的工具。以下是有三种寻找插件的好方法：

• awesome-remark 和 awesome-rehype —— 精选最出色的项目
• remark 插件列表 和 rehype 插件列表 —— 所有插件的列表
• remark-plugin 和 rehype-plugin 主题 —— GitHub 上所有标记的仓库

语法

react-markdown 默认遵循 CommonMark，以标准化不同 Markdown 实现之间的差异。 一些语法扩展通过插件支持。

我们在底层使用 micromark 进行解析。 查阅其文档以获取更多关于 Markdown、CommonMark 和扩展的信息。

兼容性

由 unified 集体维护的项目与维护版本的 Node.js 兼容。

当我们发布一个新的主要版本时，我们会放弃对不再维护的 Node 版本的支持。 这意味着我们尝试保持当前发布线，react-markdown@10，与 Node.js 16 兼容。

它们在所有现代浏览器中都能工作（基本上是除了 IE 11）。 您可以使用打包工具（如 esbuild、webpack 或 Rollup）在您的项目中使用这个包， 并使用其选项（或插件）为旧版浏览器添加支持。

架构

                                                           react-markdown
         +----------------------------------------------------------------------------------------------------------------+
         |                                                                                                                |
         |  +----------+        +----------------+        +---------------+       +----------------+       +------------+ |
         |  |          |        |                |        |               |       |                |       |            | |
markdown-+->+  remark  +-mdast->+ remark 插件 +-mdast->+ remark-rehype +-hast->+ rehype 插件 +-hast->+ 组件 +-+->react 元素
         |  |          |        |                |        |               |       |                |       |            | |
         |  +----------+        +----------------+        +---------------+       +----------------+       +------------+ |
         |                                                                                                                |
         +----------------------------------------------------------------------------------------------------------------+

要了解这个项目的作用，首先重要的是了解 unified 是如何工作的：请阅读 unifiedjs/unified 的自述文件 （直到您看到 API 部分是必读的）。

react-markdown 是一个 unified 管道 —— 包装得如此，大多数用户无需直接与 unified 交互。 处理器会经历以下步骤：

• 将 Markdown 解析为 mdast（Markdown 语法树）
• 通过 remark（Markdown 生态系统）进行转换
• 将 mdast 转换为 hast（HTML 语法树）
• 通过 rehype（HTML 生态系统）进行转换
• 使用组件将 hast 渲染为 React

附录 A：Markdown 中的 HTML

react-markdown 通常会转义 HTML（或者在启用 skipHtml 时忽略它），因为它是不安全的，且违背了此库的初衷。

然而，如果您处于受信任的环境（您信任 Markdown），并且可以牺牲包大小（±60kb minzipped），那么您可以使用 rehype-raw：

import React from 'react'
import {createRoot} from 'react-dom/client'
import Markdown from 'react-markdown'
import rehypeRaw from 'rehype-raw'

const markdown = `<div class="note">

Some *emphasis* and <strong>strong</strong>!

</div>`

createRoot(document.body).render(
  <Markdown rehypePlugins={[rehypeRaw]}>{markdown}</Markdown>
)

<div className="note">
  <p>
    Some <em>emphasis</em> and <strong>strong</strong>!
  </p>
</div>

注意：Markdown 中的 HTML 仍然受 CommonMark 中 HTML 的运作方式的限制。确保在包含 Markdown 的块级 HTML 周围使用空行！

附录 B：组件

您还可以更改来自 Markdown 的内容：

<Markdown
  components={{
    // Map `h1` (`# heading`) to use `h2`s.
    h1: 'h2',
    // Rewrite `em`s (`*like so*`) to `i` with a red foreground color.
    em(props) {
      const {node, ...rest} = props
      return <i style={{color: 'red'}} {...rest} />
    }
  }}
/>

组件中的键是您使用 Markdown 编写的元素的 HTML 对应项（例如，h1 对应 # 标题）。 在 Markdown 中，通常包括以下元素：a、blockquote、br、code、em、h1、h2、h3、h4、h5、h6、hr、img、li、ol、p、pre、strong 和 ul。 借助 remark-gfm，您还可以使用 del、input、table、tbody、td、th、thead 和 tr。 其他 remark 或 rehype 插件，如果添加了对新结构支持，同样可以与 react-markdown 配合使用。

传递的属性是您可能期望的：a（链接）将获得 href（以及 title）属性，而 img（图片）将获得 src、alt 和 title 等。

每个组件都会接收到一个 node。 这是原始的 Element 来自 hast 元素，将被转换成 React 元素。

附录 C：Markdown（和 JSX）中的行结束

您可能会遇到 Markdown 和 JSX 中行结束的处理问题。 我们建议如下，这将解决所有行结束问题：

// If you write actual markdown in your code, put your markdown in a variable;
// **do not indent markdown**:
const markdown = `
# This is perfect!
`

// Pass the value as an expression as an only child:
const result = <Markdown>{markdown}</Markdown>

👆 这有效。

继续阅读了解哪些不行以及原因。

你可能会尝试直接在 JSX 中编写 Markdown 并发现它无法工作：

<Markdown>
  # Hi

  This is **not** a paragraph.
</Markdown>

这是因为在使用 JSX 时，空白字符（包括行结束符）会被折叠为单个空格。 因此，上述示例等价于：

<Markdown> # Hi This is **not** a paragraph. </Markdown>

相反，要将 Markdown 传递给 Markdown，您可以使用一个表达式： 配合模板字符串：

<Markdown>{`
# Hi

This is a paragraph.
`}</Markdown>

模板字面量存在另一个潜在问题，因为它们会保留其中的空白（包括缩进）。 这意味着以下内容不会变成标题：

<Markdown>{`
    # This is **not** a heading, it’s an indented code block
`}</Markdown>

安全性

默认情况下，使用 react-markdown 是安全的。 如果覆盖 urlTransform 为不安全的值，将会使你面临 XSS 攻击向量。 此外，你使用的 remarkPlugins、rehypePlugins 和 components 可能也不安全。

为了确保内容即使在插件处理后也完全安全，请使用 rehype-sanitize。 它允许你定义自己的允许与禁止的规则。

相关项目

• MDX — Markdown 中的 JSX
• remark-gfm — 添加对 GitHub 风格 Markdown 的支持
• react-remark — 基于钩子的替代方法
• rehype-react — 将 HTML 转换为 React 元素

贡献指南

查看 contributing.md 在 remarkjs/.github 以了解如何开始贡献。 查看 support.md 以获取帮助的方式。

本项目有 行为准则。 通过与这个仓库、组织或社区互动，你同意遵守其条款。

许可

MIT © Espen Hovlandsdal