使用 MDX#

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

Markdown#

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

# Hello World

使用组件#

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

import { CustomComponent } from './custom';

# Hello World

<CustomComponent />

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

import Foo from './shared/foo.mdx';

# Hello world

<Foo />

// <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`
:::

输出：

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:

代码块#

基本使用#

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

输入:

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

```js title="hello.js"
console.log('Hello World');
```

输出:

console.log('Hello World');

console.log('Hello World');

代码行高亮#

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

输入:

```js {1,3-5}
console.log('Hello World');

const a = 1;
console.log(a);
const b = 2;
console.log(b);
```

输出:

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);
```

输出:

1console.log('Hello World');
2
3const a = 1;
4
5console.log(a);
6
7const b = 2;
8
9console.log(b);

显示代码行号#

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

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

Wrap Code#

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

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 版本编译器，默认开启。比如：

import { defineConfig } from 'rspress/config';

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

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

import { defineConfig } from 'rspress/config';

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