版本：3.8.1

MDX 和 React

Docusaurus has built-in support for MDX, which allows you to write JSX within your Markdown files and render them as React components.

Check out the MDX docs to see what fancy stuff you can do with MDX.

Debugging MDX

MDX格式是相当严格的，您可能会遇到编译错误。

Use the MDX playground to debug them and make sure your syntax is valid.

信息

Prettier, the most popular formatter, supports only the legacy MDX v1. If you get an unintentional formatting result, you may want to add {/* prettier-ignore */} before the problematic area, or add *.mdx to your .prettierignore, until Prettier has proper support for MDX v3. One of the main authors of MDX recommends remark-cli with remark-mdx.

Exporting components

To define any custom component within an MDX file, you have to export it: only paragraphs that start with export will be parsed as components instead of prose.

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!

MDX is JSX

由于所有文档文件都是使用MDX解析的，任何看起来像HTML的内容实际上是JSX语法。因此，如果您需要对组件进行内联样式处理，请遵循JSX风格，并提供样式对象。

/* Instead of this: */
<span style="background-color: red">Foo</span>
/* Use this: */
<span style={{backgroundColor: 'red'}}>Foo</span>

Importing components

您还可以导入其他文件中定义的自己的组件或通过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';

提示

The @site alias points to your website's directory, usually where the docusaurus.config.js file is. Using an alias instead of relative paths ('../../src/components/BrowserWindow') saves you from updating import paths when moving files around, or when versioning docs and translating.

对于简单的情况，在 Markdown 中直接声明组件非常方便，但由于编辑器的支持有限，有解析错误的风险，以及可复用性低，这种做法长期来看很难维护。 Use a separate .js file when your component involves complex JS logic:

src/components/Highlight.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>
  );
}

markdown-file.mdx
import Highlight from '@site/src/components/Highlight';

<Highlight color="#25c2a0">Docusaurus green</Highlight>

提示

如果你在许多文件中都用到了同一个组件，你不需要每一次都导入它——你可以考虑把它添加到全局范围导入。 See below

MDX component scope

Apart from importing a component and exporting a component, a third way to use a component in MDX is to register it to the global scope, which will make it automatically available in every MDX file, without any import statements.

例如，在下面给定的 MDX 文件中：

- a
- list!

And some <Highlight>custom markup</Highlight>...

It will be compiled to a React component containing ul, li, p, and Highlight elements. Highlight is not a native html element: you need to provide your own React component implementation for it.

In Docusaurus, the MDX component scope is provided by the @theme/MDXComponents file. It's not a React component, per se, unlike most other exports under the @theme/ alias: it is a record from tag names like Highlight to their React component implementations.

If you swizzle this component, you will find all tags that have been implemented, and you can further customize our implementation by swizzling the respective sub-component, like @theme/MDXComponents/Code (which is used to render Markdown code blocks).

If you want to register extra tag names (like the <Highlight> tag above), you should consider wrapping @theme/MDXComponents, so you don't have to maintain all the existing mappings. 由于目前 Swizzle CLI 工具还不支持对非组件文件进行包装处理，所以你得手动创建包装器：

src/theme/MDXComponents.js
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,
};

And now, you can freely use <Highlight> in every page, without writing the import statement:

I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!

http://localhost:3000

I can conveniently use Docusaurus green everywhere!

警告

We use upper-case tag names like Highlight on purpose.

From MDX v3+ onward (Docusaurus v3+), lower-case tag names are always rendered as native html elements, and will not use any component mapping you provide.

警告

This feature is powered by an MDXProvider. If you are importing Markdown in a React page, you have to supply this provider yourself through the MDXContent theme component.

src/pages/index.js
import React from 'react';
import FeatureDisplay from './_featureDisplay.mdx';
import MDXContent from '@theme/MDXContent';

export default function LandingPage() {
  return (
    <div>
      <MDXContent>
        <FeatureDisplay />
      </MDXContent>
    </div>
  );
}

If you don't wrap your imported MDX with MDXContent, the global scope will not be available.

Markdown and JSX interoperability

Docusaurus v3 is using MDX v3.

The MDX syntax is mostly compatible with CommonMark, but is much stricter because your .mdx files can use JSX and are compiled into real React components (check the playground).

Some valid CommonMark features won't work with MDX (more info), notably:

Indented code blocks: use triple backticks instead
Autolinks (<http://localhost:3000>): use regular link syntax instead ([http://localhost:3000](http://localhost:3000))
HTML syntax (<p style="color: red;">): use JSX instead (<p style={{color: 'red'}}>)
Unescaped { and <: escape them with \ instead (\{ and \<)

Experimental CommonMark support

Docusaurus v3 makes it possible to opt-in for a less strict, standard CommonMark support with the following options:

The mdx.format: md front matter
The .md file extension combined with the siteConfig.markdown.format: "detect" configuration

This feature is experimental and currently has a few limitations.

Importing code snippets

You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to Webpack raw-loader. In order to use raw-loader, you first need to install it in your project:

npm
Yarn
pnpm
Bun

npm install --save raw-loader

yarn add raw-loader

pnpm add raw-loader

bun add raw-loader

现在您可以从另一个文件导入代码片段：

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

<CodeBlock 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>
  );
}

See using code blocks in JSX for more details of the <CodeBlock> component.

备注

You have to use <CodeBlock> rather than the Markdown triple-backtick ```, because the latter will ship out any of its content as-is, but you want to interpolate the imported text here.

警告

这个功能是试验性的，未来 API 可能会有破坏性变更。

Importing Markdown

You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages. Each MDX file default-exports its page content as a React component. 在 "import" 语句中，您可以使用任何名称默认导入此组件，但它必须按照React的命名规则大写。

By convention, using the _ filename prefix will not create any doc page and means the Markdown file is a "partial", to be imported by other files.

_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

Hello Sebastien

This is text some content from _markdown-partial-example.md.

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

Available exports

在 MDX 页面内，以下变量可作为全局变量：

frontMatter: the front matter as a record of string keys and values;
toc: the table of contents, as a tree of headings. See also Inline TOC for a more concrete use-case.
contentTitle: the Markdown title, which is the first h1 heading in the Markdown text. It's undefined if there isn't one (e.g. title specified in the front matter).

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>

http://localhost:3000

The table of contents for this page, serialized:

[
  {
    "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
  }
]

The front matter of this page:

id: react
description: 得益于 MDX，你可以在 Docusaurus Markdown 文档中使用 React
slug: /markdown-features/react

The title of this page is: MDX 和 React

Exporting components​

Importing components​

MDX component scope​

Markdown and JSX interoperability​

Importing code snippets​

Importing Markdown​

Available exports​

Exporting components

Importing components

MDX component scope

Markdown and JSX interoperability

Importing code snippets

Importing Markdown

Available exports