使用 MDX
Rspress 支持 MDX,这是一种功能强大的内容开发方式。
Markdown
MDX 是 Markdown 的超集,这意味着你可以像往常一样编写 Markdown 文件。例如:
使用组件
当你想在 Markdown 文件中使用 React 组件时,你应该使用 .mdx
扩展名来命名你的文件。例如:
// docs/index.mdx
import { CustomComponent } from './custom';
# Hello World
<CustomComponent />
Front Matter
你可以在 Markdown 文件的开头添加 Front Matter,它是一个 YAML 格式的对象,用于定义一些元数据。例如:
---
title: Hello World
---
注意:默认情况下,Rspress 使用 h1 标题作为 html 的标题。
你还可以在正文中访问 Front Mattter 中定义的属性,例如:
---
title: Hello World
---
# {frontmatter.title}
前面定义的属性将作为 frontmatter
属性传递给组件。所以最终输出将是:
自定义容器
你可以使用 :::
语法来创建自定义容器,且支持自定义标题。例如:
输入:
:::tip
这是一个 `tip` 类型的 `block`
:::
:::info
这是一个 `info` 类型的 `block`
:::
:::warning
这是一个 `warning` 类型的 `block`
:::
:::danger
这是一个 `danger` 类型的 `block`
:::
::: details
这是一个 `details` of type `block`
:::
:::tip 自定义标题
自定义标题的 `block`
:::
:::tip{title=自定义标题}
自定义标题的 `block`
:::
输出:
DETAILS
这是一个 details
of type block
代码块
基本使用
你可以使用 ``` 语法来创建代码块,且支持自定义标题。例如:
输入:
```js
console.log('Hello World');
```
```js title="hello.js"
console.log('Hello World');
```
输出:
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);
```
输出:
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
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 的插件。