|
|
|
@@ -0,0 +1,210 @@ |
|
|
|
# Markdown & MDX |
|
|
|
|
|
|
|
Rspress supports not only Markdown but also [MDX](https://mdxjs.com/), a powerful way to develop content. |
|
|
|
|
|
|
|
## Markdown |
|
|
|
|
|
|
|
MDX is a superset of Markdown, which means you can write Markdown files as usual. For example: |
|
|
|
|
|
|
|
```md |
|
|
|
# Hello world |
|
|
|
``` |
|
|
|
|
|
|
|
## Use component |
|
|
|
|
|
|
|
When you want to use React components in Markdown files, you should name your files with `.mdx` extension. For example: |
|
|
|
|
|
|
|
```mdx |
|
|
|
// 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: |
|
|
|
|
|
|
|
```yaml |
|
|
|
--- |
|
|
|
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: |
|
|
|
|
|
|
|
```markdown |
|
|
|
--- |
|
|
|
title: Hello world |
|
|
|
--- |
|
|
|
|
|
|
|
# {frontmatter.title} |
|
|
|
``` |
|
|
|
|
|
|
|
The previously defined properties will be passed to the component as `frontmatter` properties. So the final output will be: |
|
|
|
|
|
|
|
```html |
|
|
|
<h1>Hello world</h1> |
|
|
|
``` |
|
|
|
|
|
|
|
## Custom container |
|
|
|
|
|
|
|
You can use the `:::` syntax to create custom containers and support custom titles. For example: |
|
|
|
|
|
|
|
**Input:** |
|
|
|
|
|
|
|
```markdown |
|
|
|
:::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` |
|
|
|
::: |
|
|
|
|
|
|
|
:::tip Custom Title |
|
|
|
This is a `block` of `Custom Title` |
|
|
|
::: |
|
|
|
|
|
|
|
:::tip{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:** |
|
|
|
|
|
|
|
````md |
|
|
|
```js |
|
|
|
console.log('Hello World'); |
|
|
|
``` |
|
|
|
|
|
|
|
```js title="hello.js" |
|
|
|
console.log('Hello World'); |
|
|
|
``` |
|
|
|
```` |
|
|
|
|
|
|
|
**Output:** |
|
|
|
|
|
|
|
```js |
|
|
|
console.log('Hello World'); |
|
|
|
``` |
|
|
|
|
|
|
|
```js title="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: |
|
|
|
|
|
|
|
```ts title="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: |
|
|
|
|
|
|
|
```ts title="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:** |
|
|
|
|
|
|
|
````md |
|
|
|
```js title="hello.js" {1,3-5} |
|
|
|
console.log('Hello World'); |
|
|
|
|
|
|
|
const a = 1; |
|
|
|
|
|
|
|
console.log(a); |
|
|
|
|
|
|
|
const b = 2; |
|
|
|
|
|
|
|
console.log(b); |
|
|
|
``` |
|
|
|
```` |
|
|
|
|
|
|
|
**Output:** |
|
|
|
|
|
|
|
```js title="hello.js" {1,3-5} |
|
|
|
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: |