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:

index.mdx
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 />
TIP

Relevant components need to be excluded from routing meta info through route.exclude configuration.

You can also place components in an adjacent directory outside root. For example:

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

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:

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

Custom Title

This is a block of Custom Title

Custom Title

This is a block of Custom Title

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');
hello.js
console.log('Hello World');

Show Line Numbers

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

rspress.config.ts
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:

rspress.config.ts
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:

hello.js
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:

rspress.config.ts
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:

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

The bottom layer of mdxRs is based on the @rspress/mdx-rs-binding library developed by Rspress. The performance is 10+ times higher than the JS version of the MDX compiler, but the JS version of the plugin is not yet supported.