源码解析
源码解析

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:

# Hello World

Use Component

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

// docs/index.mdx import { CustomComponent } from './custom'; # Hello World <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:

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

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

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
console.log('Hello World'); const a = 1; console.log(a); const b = 2; console.log(b);

Rustify MDX compiler

You can enable Rustify MDX compiler by following config: