使用 MDX

Rspress 支持 MDX，这是一种功能强大的内容开发方式。

Markdown

MDX 是 Markdown 的超集，这意味着你可以像往常一样编写 Markdown 文件。例如：

# Hello World

使用组件

当你想在 Markdown 文件中使用 React 组件时，你应该使用 .mdx 扩展名来命名你的文件。例如：

index.mdx

import { CustomComponent } from './custom';
# Hello World
<CustomComponent />

所有的 mdx 文件也被视为组件，它们可以被互相引用：

import Foo from './shared/foo.mdx';
# Hello world
<Foo />

TIP

相关组件需要通过 route.exclude 配置从路由信息中排除。

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

// <cwd>/docs/index.mdx
import { Button } from '../components/button';
# Button
<Button />
// <cwd>/components/button.mdx
export Button = () => <button />;

Front Matter

你可以在 Markdown 文件的开头添加 Front Matter，它是一个 YAML 格式的对象，用于定义一些元数据。例如：

---
title: Hello World
---

注意：默认情况下，Rspress 使用 h1 标题作为 html 的标题。

你还可以在正文中访问 Front Mattter 中定义的属性，例如：

---
title: Hello World
---
# {frontmatter.title}

前面定义的属性将作为 frontmatter 属性传递给组件。所以最终输出将是：

<h1>Hello World</h1>

自定义容器

::: 语法

你可以使用 ::: 语法来创建自定义容器，且支持自定义标题。例如：

输入：

:::note
这是一个 `note` 类型的 `block`
:::
:::tip
这是一个 `tip` 类型的 `block`
:::
:::info
这是一个 `info` 类型的 `block`
:::
:::warning
这是一个 `warning` 类型的 `block`
:::
:::danger
这是一个 `danger` 类型的 `block`
:::
:::details
这是一个 `details` of type `block`
:::
:::tip 自定义标题
自定义标题的 `block`
:::
:::tip{title=自定义标题}
自定义标题的 `block`
:::

输出：

NOTE

这是一个 note 类型的 block

TIP

这是一个 tip 类型的 block

INFO

这是一个 info 类型的 block

WARNING

这是一个 warning 类型的 block

DANGER

这是一个 danger 类型的 block

DETAILS

这是一个 details of type block

自定义标题

自定义标题的 block

自定义标题

自定义标题的 block

GitHub Markdown Alerts 语法

你可以使用 GitHub Markdown Alerts 语法 来创建自定义容器。

Input:

> [!NOTE]
> 这是一个 `note` 类型的 `block`
> [!TIP]
> 这是一个 `tip` 类型的 `block`
> [!INFO]
> 这是一个 `info` 类型的 `block`
> [!WARNING]
> 这是一个 `warning` 类型的 `block`
> [!DANGER]
> 这是一个 `danger` 类型的 `block`
> [!DETAILS]
> 这是一个 `details` 类型的 `block`

Output:

NOTE

这是一个 note 类型的 block

TIP

这是一个 tip 类型的 block

INFO

这是一个 info 类型的 block

WARNING

这是一个 warning 类型的 block

DANGER

这是一个 danger 类型的 block

DETAILS

这是一个 details 类型的 block

代码块

基本使用

你可以使用 ``` 语法来创建代码块，且支持自定义标题。例如：

输入:

```js
console.log('Hello World');

```js title=”hello.js” console.log(‘Hello World’);

```
**输出:**
```js
console.log('Hello World');

hello.js

console.log('Hello World');

代码行高亮

你可以通过如下的语法指定代码行高亮，比如:

输入:

```js {1,3-5}
console.log('Hello World');
const a = 1;
console.log(a);
const b = 2;
console.log(b);

**输出:**
```js
1console.log('Hello World');
2
3const a = 1;
4console.log(a);
5const b = 2;
6console.log(b);

你也可以同时应用代码行高亮和代码块标题，比如:

输入:

```js title="hello.js" {1,3-5}
console.log('Hello World');
const a = 1;
console.log(a);
const b = 2;
console.log(b);

**输出:**
hello.js
```js
1console.log('Hello World');
2
3const a = 1;
4
5console.log(a);
6
7const b = 2;
8
9console.log(b);

显示代码行号

如果你想要显示代码行号，你可以在配置文件中开启 showLineNumbers 选项:

rspress.config.ts

export default {
  // ...
  markdown: {
    showLineNumbers: true,
  },
};

Wrap Code

如果你想要默认启用长代码换行展示，你可以在配置文件中开启 defaultWrapCode 选项:

rspress.config.ts

export default {
  // ...
  markdown: {
    defaultWrapCode: true,
  },
};

自定义锚点 id

默认情况下，Rspress 会根据各个标题的内容自动生成 id，这个 id 也会作为锚点的内容，你可以通过如下的语法来自定义 header 的 id:

## Hello World \{#custom-id}

其中 custom-id 就是你自定义的 id。

关闭 Rust 版本编译器

默认情况下，Rspress 使用 Rust 版本的 MDX 编译器，但是在某些情况下，你需要添加自定义的 MDX 编译插件，此时你可以通过如下的配置关闭 Rust 版本的 MDX 编译器，从而切换到 JavaScript 版本的编译器:

是否使用 MDX 的 Rust 版本编译器，默认开启。比如：

rspress.config.ts

import { defineConfig } from 'rspress/config';
export default defineConfig({
  markdown: {
    // 使用 JS 版本的 MDX 编译器
    mdxRs: false,
  },
});

你也可以提供函数来决定哪些文件使用 MDX 的 Rust 版本编译器。比如：

rspress.config.ts

import { defineConfig } from 'rspress/config';
export default defineConfig({
  markdown: {
    mdxRs: {
      include: (filepath: string) => filepath.includes('foo.mdx'),
    },
  },
});

注意

mdxRs 能力底层基于 Rspress 自研的 @rspress/mdx-rs 库来实现，性能比 JS 版本的 MDX 编译器提升 10 倍以上，但不支持 JS 的插件。