Markdown & MDX#

Rspress supports not only Markdown but also MDX, a powerful way to develop content.

Markdown#

MDX is a superset of Markdown, which means you can write Markdown files as usual. For example:

1# Hello world

Use component#

When you want to use React components in Markdown files, you should name your files with .mdx extension. For example:

1// docs/index.mdx
2import { CustomComponent } from './custom';
3
4# Hello world
5
6<CustomComponent />

Front matter#

You can add Front Matter at the beginning of your Markdown file, which is a YAML-formatted object that defines some metadata. For example:

1---
2title: Hello world
3---

Note: By default, Rspress uses h1 headings as html headings.

You can also access properties defined in Front Matter in the body, for example:

1---
2title: Hello world
3---
4
5# {frontmatter.title}

The previously defined properties will be passed to the component as frontmatter properties. So the final output will be:

1<h1>Hello world</h1>

Custom container#

You can use the ::: syntax to create custom containers and support custom titles. For example:

Input:

1:::tip
2This is a `block` of type `tip`
3:::
4
5:::info
6This is a `block` of type `info`
7:::
8
9:::warning
10This is a `block` of type `warning`
11:::
12
13:::danger
14This is a `block` of type `danger`
15:::
16
17::: details
18This is a `block` of type `details`
19:::
20
21:::tip Custom Title
22This is a `block` of `Custom Title`
23:::
24
25:::tip{title="Custom Title"}
26This is a `block` of `Custom Title`
27:::

Output:

Code block#

Basic usage#

You can use the ``` syntax to create code blocks and support custom titles. For example:

Input:

1```js
2console.log('Hello World');
3```
4
5```js title="hello.js"
6console.log('Hello World');
7```

Output:

1console.log('Hello World');

1console.log('Hello World');

Show line numbers#

If you want to display line numbers, you can enable the showLineNumbers option in the config file:

1export default {
2  // ...
3  markdown: {
4    showLineNumbers: true,
5  },
6};

Wrap code#

If you want to wrap long code line by default, you can enable the defaultWrapCode option in the config file:

1export default {
2  // ...
3  markdown: {
4    defaultWrapCode: true,
5  },
6};

Line highlighting#

You can also apply line highlighting and code block title at the same time, for example:

Input:

1```js title="hello.js" {1,3-5}
2console.log('Hello World');
3
4const a = 1;
5
6console.log(a);
7
8const b = 2;
9
10console.log(b);
11```

Output:

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

Rustify MDX compiler#

You can enable Rustify MDX compiler by following config: