跳转至主内容
Version: 2.0.0-beta.9

MDX 和 React

在 Markdown 中使用 JSX

Docusaurus 原生支持 MDX v1,可以直接在 Markdown 文档中编写 JSX,并渲染为 React 组件。

note

虽然 .md.mdx 文件都使用 MDX 解析,有些语法的处理方式却不太一样。 为了得到最准确的解析结果和更好的编辑器支持,推荐包含 MDX 语法的文档使用.mdx 后缀。

caution

MDX 并不 100% 兼容 CommonMark

使用 MDX 在线示例 来确保符合正确的 MDX 语法。

例如使用下面的文档示例:

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 语法的:

http://localhost:3000
Docusaurus green and Facebook blue are my favorite colors.

I can write Markdown alongside my JSX!


你也可以导入其它目录中的组件,或者通过 npm 安装的第三方库提供的组件! 访问 MDX 文档 来看看 MDX 还能做哪些更神奇的事。

caution

因为所有文档都是使用 MDX 解析的,所有的 HTML 标签都会被认为是 JSX。 因此,如果想使用内联样式,要使用 JSX 语法,即给 style 的值设置为 JavaScript 对象。 这里跟 Docusaurus 1 是不一样的。 参考 从 v1 迁移到 v2

导入原始代码

除了能从文件中导入 React 组件外,你还能把文件中的代码直接导入为普通文本,并把它插入到代码块中,作为文档的代码示例进行展示,感谢 Webpack raw-loader。 要使用 raw-loader,需要先进行安装:

npm install --save raw-loader

这时你就可以从文件中原样导入代码了:

myMarkdownFile.mdx
import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';

<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>
http://localhost:3000
/**
* 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 组件传递 title 属性,来在代码块上方显示代码块标题。

<CodeBlock className="language-jsx" title="/src/myComponent">
{MyComponentSource}
</CodeBlock>
note

要注意的是,显示导入进来的代码必须使用 <CodeBlock> 组件,不能使用 Markdown 的 ``` 语法,因为它不会对表达式求值,而是原样显示传给它的内容,而使用 JSX 的形式可以对导入进来的变量进行求值并展示。

warning

这个特性是试验性的,后面可能会根据 API 的变化而修改。

导入 Markdown

你可以把 Markdown 文档当作 React 组件,在其它 Markdown 文件或 React 组件中导入。

按照约定,使用 _ 作为文件名前缀 的文档不会生成页面,而是作为"片段(Partial)" 来让其它文件导入。

_markdown-partial-example.mdx
<span>Hello {props.name}</span>

This is text some content from `_markdown-partial-example.mdx`.
someOtherDoc.mdx
import PartialExample from './_markdown-partial-example.mdx';

<PartialExample name="Sebastien" />;
http://localhost:3000
您好 Sebastien

这是来自 _markdown-partial-example.md 的一些文本。


这样,你可以在多个文档中复用内容,避免重复编写。

caution

如果使用这种方式导入的内容作为 Markdown 文档中的小标题,那么它们是不会包含在目录中的。 这是由于技术限制,我们正在努力解决:(issue)。