MDX 和 React
Docusaurus 内置支持 MDX,它允许你在 Markdown 文件中编写 JSX 并将其渲染为 React 组件。
查看 MDX 文档,了解你可以使用 MDX 做哪些花哨的事情。
MDX 格式非常严格,你可能会遇到编译错误。
使用 MDX Playground 来调试它们,并确保你的语法是有效的。
最流行的格式化工具 Prettier 仅支持旧版 MDX v1。如果你得到一个意料之外的格式化结果,你可能需要在有问题区域之前添加 {/* prettier-ignore */}
,或者将 *.mdx
添加到你的 .prettierignore
文件中,直到 Prettier 正式支持 MDX v3。MDX 的主要作者之一推荐使用 remark-cli
和 remark-mdx
。
导出组件
要在 MDX 文件中定义任何自定义组件,你必须将其导出:只有以 export
开头的段落才会被解析为组件而不是散文。
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
注意它如何同时渲染来自 React 组件的标记和 Markdown 语法
我可以同时编写 Markdown 和我的 JSX!
由于所有文档文件都使用 MDX 解析,任何看起来像 HTML 的内容实际上都是 JSX。因此,如果你需要为组件设置内联样式,请遵循 JSX 风格并提供样式对象。
/* Instead of this: */
<span style="background-color: red">Foo</span>
/* Use this: */
<span style={{backgroundColor: 'red'}}>Foo</span>
导入组件
你还可以导入在其他文件中定义的自定义组件,或通过 npm 安装的第三方组件。
<!-- Docusaurus theme component -->
import TOCInline from '@theme/TOCInline';
<!-- External component -->
import Button from '@mui/material/Button';
<!-- Custom component -->
import BrowserWindow from '@site/src/components/BrowserWindow';
虽然在 Markdown 中声明组件对于简单情况非常方便,但由于有限的编辑器支持、解析错误的风险以及低可重用性,它变得难以维护。当你的组件涉及复杂的 JS 逻辑时,请使用单独的 .js
文件
import React from 'react';
export default function Highlight({children, color}) {
return (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
}
import Highlight from '@site/src/components/Highlight';
<Highlight color="#25c2a0">Docusaurus green</Highlight>
如果你在许多文件中使用相同的组件,则无需在每个地方都导入它——可以考虑将其添加到全局作用域中。参见下文
MDX 组件作用域
除了导入组件和导出组件之外,在 MDX 中使用组件的第三种方法是将其注册到全局作用域,这将使其在每个 MDX 文件中自动可用,无需任何导入语句。
例如,给定这个 MDX 文件
- a
- list!
And some <Highlight>custom markup</Highlight>...
它将被编译成一个包含 ul
、li
、p
和 Highlight
元素的 React 组件。Highlight
不是一个原生的 HTML 元素:你需要为它提供自己的 React 组件实现。
在 Docusaurus 中,MDX 组件作用域由 @theme/MDXComponents
文件提供。它本身并不是一个 React 组件,不像 @theme/
别名下的其他大多数导出:它是一个从标签名(如 Highlight
)到其 React 组件实现的记录。
如果你修改此组件,你将找到所有已实现的标签,你可以通过修改相应的子组件(如 @theme/MDXComponents/Code
,用于渲染Markdown 代码块)来进一步自定义我们的实现。
如果你想注册额外的标签名(例如上面的 <Highlight>
标签),你应该考虑包装 @theme/MDXComponents
,这样你就无需维护所有现有的映射。由于 swizzle CLI 尚不支持包装非组件文件,你应该手动创建包装器
import React from 'react';
// Import the original mapper
import MDXComponents from '@theme-original/MDXComponents';
import Highlight from '@site/src/components/Highlight';
export default {
// Re-use the default mapping
...MDXComponents,
// Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `<Highlight>` in MDX
Highlight,
};
现在,你可以在每个页面中自由使用 <Highlight>
,而无需编写导入语句
I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
我可以很方便地在任何地方使用 Docusaurus 绿!
我们特意使用大写的标签名,如 Highlight
。
从 MDX v3+(Docusaurus v3+)开始,小写标签名总是被渲染为原生 HTML 元素,并且不会使用你提供的任何组件映射。
此功能由 MDXProvider
提供支持。如果你在 React 页面中导入 Markdown,你必须通过 MDXContent
主题组件自行提供此 provider。
import React from 'react';
import FeatureDisplay from './_featureDisplay.mdx';
import MDXContent from '@theme/MDXContent';
export default function LandingPage() {
return (
<div>
<MDXContent>
<FeatureDisplay />
</MDXContent>
</div>
);
}
如果你不将导入的 MDX 包装在 MDXContent
中,全局作用域将不可用。
Markdown 和 JSX 互操作性
Docusaurus v3 正在使用 MDX v3。
MDX 语法大体上与 CommonMark 兼容,但更严格,因为你的 .mdx
文件可以使用 JSX 并被编译成真实的 React 组件(查看 Playground)。
一些有效的 CommonMark 功能将无法与 MDX 一起使用(更多信息),特别是:
- 缩进代码块:请改用三反引号
- 自动链接(
<https://:3000>
):请改用常规链接语法([https://:3000](https://:3000)
) - HTML 语法(
<p style="color: red;">
):请改用 JSX(<p style={{color: 'red'}}>
) - 未转义的
{
和<
:请改用\
转义它们(\{
和\<
)
Docusaurus v3 允许通过以下选项选择更宽松的标准 CommonMark 支持:
mdx.format: md
前言.md
文件扩展名与siteConfig.markdown.format: "detect"
配置结合使用
此功能是实验性的,目前存在一些限制。
导入代码片段
你不仅可以导入包含组件定义的文件,还可以将任何代码文件作为纯文本导入,然后将其插入代码块中,这要归功于 Webpack raw-loader。要使用 raw-loader
,你首先需要在你的项目中安装它
- npm
- Yarn
- pnpm
- Bun
npm install --save raw-loader
yarn add raw-loader
pnpm add raw-loader
bun add raw-loader
现在你可以按原样从另一个文件导入代码片段了
import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';
<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import React, {useState} from 'react';
export default function MyComponent() {
const [bool, setBool] = useState(false);
return (
<div>
<p>MyComponent rendered !</p>
<p>bool={bool ? 'true' : 'false'}</p>
<p>
<button onClick={() => setBool((b) => !b)}>toggle bool</button>
</p>
</div>
);
}
有关 <CodeBlock>
组件的更多详细信息,请参阅在 JSX 中使用代码块。
你必须使用 <CodeBlock>
而不是 Markdown 三反引号 ```
,因为后者会按原样输出其内容,但你希望在此处插入导入的文本。
此功能是实验性的,未来可能会发生破坏性的 API 更改。
导入 Markdown
你可以将 Markdown 文件用作组件并将其导入到其他地方,无论是在 Markdown 文件中还是在 React 页面中。每个 MDX 文件都默认将其页面内容导出为一个 React 组件。在 import
语句中,你可以用任何名称默认导入此组件,但它必须遵循 React 的命名规则以首字母大写。
按照惯例,使用 _
文件名前缀不会创建任何文档页面,这意味着该 Markdown 文件是一个“局部”文件,供其他文件导入。
<span>Hello {props.name}</span>
This is text some content from `_markdown-partial-example.mdx`.
import PartialExample from './_markdown-partial-example.mdx';
<PartialExample name="Sebastien" />
这是来自 _markdown-partial-example.md
的一些文本内容。
通过这种方式,你可以在多个页面之间重用内容并避免重复资料。
可用导出
在 MDX 页面中,以下变量作为全局变量可用:
frontMatter
:前言,作为字符串键值对的记录;toc
:目录,作为标题树。另请参阅内联目录以了解更具体的用例。contentTitle
:Markdown 标题,是 Markdown 文本中的第一个h1
标题。如果没有(例如,在 front matter 中指定了标题),则为undefined
。
import TOCInline from '@theme/TOCInline';
import CodeBlock from '@theme/CodeBlock';
The table of contents for this page, serialized:
<CodeBlock className="language-json">{JSON.stringify(toc, null, 2)}</CodeBlock>
The front matter of this page:
<ul>
{Object.entries(frontMatter).map(([key, value]) => <li key={key}><b>{key}</b>: {value}</li>)}
</ul>
<p>The title of this page is: <b>{contentTitle}</b></p>
此页面的目录,序列化后
[
{
"value": "Exporting components",
"id": "exporting-components",
"level": 3
},
{
"value": "Importing components",
"id": "importing-components",
"level": 3
},
{
"value": "MDX component scope",
"id": "mdx-component-scope",
"level": 3
},
{
"value": "Markdown and JSX interoperability",
"id": "markdown-and-jsx-interoperability",
"level": 3
},
{
"value": "Importing code snippets",
"id": "importing-code-snippets",
"level": 2
},
{
"value": "Importing Markdown",
"id": "importing-markdown",
"level": 2
},
{
"value": "Available exports",
"id": "available-exports",
"level": 2
}
]
此页面的前言
- id: react
- 描述: 借助 MDX 的强大功能,在 Docusaurus Markdown 文档中使用 React
- slug: /markdown-features/react
此页面的标题是:MDX 和 React