> For AI agents: the complete documentation index is available at https://rspress.rs/zh/llms.txt, the full documentation bundle is available at https://rspress.rs/zh/llms-full.txt.

# MDX 和 React 组件

Rspress 支持 [MDX](https://mdxjs.com/)，这是一种将 Markdown 与 JSX 无缝融合的内容创作格式。MDX 允许你在文档中直接使用 React 组件，结合了 Markdown 的简洁语法和 React 生态的强大能力，非常适合构建交互式、组件化的技术文档。

## 什么是 MDX

MDX 是 Markdown 与 JSX 语法的结合，让你可以在 Markdown 文档中使用 React 组件。

我们推荐所有文档文件均使用 `.mdx`，这样既可以像普通 Markdown 一样编写内容，又能导入和使用 Rspress 提供的 [文档组件](https://rspress.rs/zh/ui/components/index.md)：

```mdx title="docs/index.mdx"
# Hello, world!

import { PackageManagerTabs } from '@rspress/core/theme';

<PackageManagerTabs command="create rspress@latest" />
```

## MDX 片段 \{#fragments}

在 MDX 中，每个 `.mdx` 文件都会编译为 React 组件，这意味着它既可以被当做组件引用，也可以自由使用 React 组件。例如：


**docs/index.mdx**

```mdx
import MdxFragment from './_mdx-fragment.mdx';
import TsxComponent from './_tsx-component';

测试 MDX 片段和 React 组件的使用。

<MdxFragment />

<TsxComponent />
```


**docs/_mdx-fragment.mdx**

```mdx file="./_mdx-fragment.mdx"
这是来自 **mdx 的片段**。

```


**docs/_tsx-component.tsx**

```tsx file="./_tsx-component.tsx"
import { useState } from 'react';

export default () => {
  const [count, setCount] = useState(0);
  return (
    <p>
      这是来自 tsx 的组件{' '}
      <button onClick={() => setCount(count => count + 1)}>{count}</button>
    </p>
  );
};

```


它将被渲染为：


测试 MDX 片段和 React 组件的使用。
这是来自 **mdx 的片段**。

这是来自 tsx 的组件 0


你可以在 `.mdx` 文件中使用 Rspress 提供的 [文档组件](https://rspress.rs/zh/ui/components/index.md) 或安装一些 React 组件库来丰富你的文档。

## 路由约定

在 [docs 目录](https://rspress.rs/zh/api/config/config-basic.md#root) 中，使用 MDX 片段或 React 组件要通过 [route.exclude](https://rspress.rs/zh/api/config/config-basic.md#routeexclude) 配置从路由中排除。为方便使用，我们约定以 "\_" 开头的文件会被 [route.excludeConvention](https://rspress.rs/zh/api/config/config-basic.md#routeexcludeconvention) 默认排除。

你也可以将组件放到 docs 目录以外的相邻目录，例如：

```tree
docs
├── _button.mdx
└── index.mdx
components
└── button.tsx
```


**docs/index.mdx**

```mdx
import ButtonFragment from './_button.mdx';
import Button from '../../components/button';

<ButtonFragment />
<Button />
```


**docs/_button.mdx**

```mdx file="./_button.mdx"
#### button

这是一段来自 MDX 的文本

```


**components/button.tsx**

```tsx
const Button = () => <button>这是来自 tsx 的按钮</button>;
export default Button;
```


它将被渲染为：


#### button

这是一段来自 MDX 的文本
这是来自 tsx 的按钮

## 逃生舱：在 tsx 中编写文档内容

```tsx file="./_escape-hatch.tsx" title="_escape-hatch.tsx"
import { getCustomMDXComponent } from '@rspress/core/theme';

export default () => {
  const { p: P, code: Code } = getCustomMDXComponent();
  return (
    <P className="rp-doc">
      这是一段在 tsx 中的内容，不过样式和在文档中的样式一样，比如
      <Code>@rspress/core</Code>。 但是 含有 className="rp-not-doc" 的这段文字
      <Code className="rp-not-doc">@rspress/core</Code> 不会生效
    </P>
  );
};

```

它将被渲染为：


这是一段在 tsx 中的内容，不过样式和在文档中的样式一样，比如`@rspress/core`。 但是 含有 className="rp-not-doc" 的这段文字`@rspress/core` 不会生效


:::warning

tsx 和 html 语法会导致静态信息难以提取，比如本地搜索索引。

更推荐使用 `.mdx` 文件来编写文档内容，使用 `.tsx` 文件来编写需交互的动态内容。

:::

## React 相关版本

| 依赖                 | 允许范围                   | 默认版本 | 说明             |
| ------------------ | ---------------------- | ---- | -------------- |
| `react`            | `^18.0.0 \|\| ^19.0.0` | 19   | 不再支持 React 17  |
| `react-dom`        | `^18.0.0 \|\| ^19.0.0` | 19   | 与 react 版本保持一致 |
| `react-router-dom` | `^6.0.0 \|\| ^7.0.0`   | 7    | 如项目已安装则使用项目版本  |

:::tip

如果你的项目中已安装 `react`、`react-dom` 或 `react-router-dom`，Rspress 会优先使用项目中安装的版本，而非内置的默认版本。

:::