#MDX 和 React 组件

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

#什么是 MDX

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

我们推荐所有文档文件均使用 .mdx，这样既可以像普通 Markdown 一样编写内容，又能导入和使用 Rspress 提供的内置组件：

# Hello, world!

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

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

#组件化

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

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

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

<MdxFragment />

<TsxComponent />

这是来自 **mdx 的片段**。

import { useState } from 'react';

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

它将被渲染为：

你可以在 .mdx 文件中使用 Rspress 提供的 内置组件 或安装一些 React 组件库来丰富你的文档。

#路由约定

在 docs 目录 中，使用 MDX 片段或 React 组件要通过 route.exclude 配置从路由中排除。为方便使用，我们约定以 "_" 开头的文件会被 route.excludeConvention 默认排除。

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

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

<ButtonFragment />
<Button />

#### button

这是一段来自 MDX 的文本

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

它将被渲染为：

#逃生舱：在 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>
  );
};

它将被渲染为：