Use MDX#

Rspress supports 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:

# Hello World

Use Component#

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

import { CustomComponent } from './custom';

# Hello World

<CustomComponent />

All mdx files are also components and they can import each other:

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#

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

---
title: Hello World
---

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

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

---
title: Hello World
---

# {frontmatter.title}

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

<h1>Hello World</h1>

Custom Container#

::: Syntax#

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

Input:

:::note
This is a `block` of type `note`
:::

:::tip
This is a `block` of type `tip`
:::

:::info
This is a `block` of type `info`
:::

:::warning
This is a `block` of type `warning`
:::

:::danger
This is a `block` of type `danger`
:::

:::details
This is a `block` of type `details`
:::

:::tip Custom Title
This is a `block` of `Custom Title`
:::

:::tip{title="Custom Title"}
This is a `block` of `Custom Title`
:::

Output:

GitHub Markdown Alerts Syntax#

You can also use GitHub Markdown Alerts Syntax to create custom containers.

Input:

> [!NOTE]
> This is a `block` of type `note`

> [!TIP]
> This is a `block` of type `tip`

> [!INFO]
> This is a `block` of type `info`

> [!WARNING]
> This is a `block` of type `warning`

> [!DANGER]
> This is a `block` of type `danger`

> [!DETAILS]
> This is a `block` of type `details`

Output:

Code Block#

Basic Usage#

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

Input:

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

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

Output:

console.log('Hello World');

console.log('Hello World');

Show Line Numbers#

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

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

Wrap Code#

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

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

Line Highlighting#

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

Input:

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

const a = 1;

console.log(a);

const b = 2;

console.log(b);
```

Ouput:

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

Customizing anchor id#

By default, Rspress will automatically generate ids based on the content of each title. This id will also serve as the content of the anchor. You can use the following syntax to customize the id of the header:

## Hello World \{#custom-id}

Where custom-id is your custom id.

Disabling the Rust Version Compiler#

In default mode, Rspress uses the Rust version of the MDX compiler, which is faster than the JavaScript version. However, the Rust version of the compiler does not support custom plugins.

If you need to add a custom MDX compiler plugin, you can disable the Rust version of the MDX compiler through the following config and switch to the JavaScript version of the compiler:

Whether to use the Rust version of the MDX compiler. For example:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  markdown: {
    // Switch to the JS version of the compiler
    mdxRs: false,
  },
});

You can also provide a function to determine which files use the Rust version of MDX compiler. For example:

import { defineConfig } from 'rspress/config';

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