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. Any amount of whitespace may separate the starting :::
block from the type declaration. Any number of colons :
greater than three may be used for the purpose of nesting.
The logic of custom containers has been partly overriden via ids, and so they mainly function as aliases, with the id
setting the actual color any symbol. This is so the same logic can apply to expandable containers, created via details
, which is not possible without it.
For example:
Input:
:::tip {id="tip"}
This is a `block` of type `tip`
:::
:::info {id="info"}
This is a `block` of type `info`
:::
:::warning {id="warning"}
This is a `block` of type `warning`
:::
:::danger {id="danger"}
This is a `block` of type `danger`
:::
::: details
This is a `block` of type `details`
:::
::: details {open}
This is a `block` of type `details`, expanded by default
:::
::::tip Custom Title
This is a `block` of `Custom Title`
:::tip {title="Custom Title but Nested!"}
This is a `block` of `Custom Title`
:::
::::
:::info {id="info"}
This is a `block` of type `info`
:::
:::info Note {id="note"}
This is a `block` of type `note`.
:::
:::details tip-but-details {id="tip"}
This is a `block` of type `tip`
:::
:::details success-but-details {open id="success"}
This is a `block` of type `success`
:::
:::details question-but-details {open id="question"}
This is a `block` of type `question`
:::
:::details warning-but-details {open id="warning"}
This is a `block` of type `warning`
:::
:::details failure-but-details {id="failure"}
This is a `block` of type `failure`
:::
:::info Danger {id="danger"}
This is a `block` of type `danger`
:::
:::info Bug {id="bug"}
This is a `block` of type `bug`
:::
:::info Abstract {id="abstract"}
This is a `block` of type `abstract`
:::
:::info Example {id="example"}
This is a `block` of type `example`
:::
:::info Quote {id="quote"}
This is a `block` of type `quote`
:::
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
Details
This is a block
of type details
, expanded by default
Custom Title
This is a block
of Custom Title
TIP
This is a block
of Custom Title
INFO
This is a block
of type info
Note
This is a block
of type note
.
tip-but-details
This is a block
of type tip
success-but-details
This is a block
of type success
question-but-details
This is a block
of type question
warning-but-details
This is a block
of type warning
failure-but-details
This is a block
of type failure
Danger
This is a block
of type danger
Bug
This is a block
of type bug
Abstract
This is a block
of type abstract
Example
This is a block
of type example
Quote
This is a block
of type quote
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:
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: