MDX 块语法大全
本站所有可用块语法的完整示例,写作时照着抄即可
本页是语法练习页,每个小节都是「先看效果、再看写法」。需要写文章时直接把「写法」里的代码复制走改内容即可。
本页是语法练习页,每个小节都是「先看效果、再看写法」。需要写文章时直接把「写法」里的代码复制走改内容即可。
一、文章头部(frontmatter)
文件最上面的 --- 之间是文章元信息,title 必填,其余可选。
写法:
---
title: "页面标题"
description: "一句话简介,会显示在标题下方"
icon: "BookOpen" # 可选,lucide 图标名
full: false # 可选,true 表示使用宽屏布局
---二、标题
标题用 ## 开始写,# 一级标题留给站点本身,正文不要用。
这是三级标题(章节内的小节)
这是四级标题(更细的拆分)
写法:
## 二级标题
### 三级标题
#### 四级标题三、段落与文字格式
普通文字直接写。段落之间必须空一行,否则会被合并成同一段。
这一段是加粗、斜体、粗斜体、删除线、行内代码 的演示。
同一段内强制换行用 <br />:
这句话被换到了新的一行。
还可以用少量 HTML 标签:下划线、荧光标记、按 Ctrl + S 保存、H2O、x2。
写法:
普通文字直接写。段落之间必须空一行。
**加粗**、*斜体*、***粗斜体***、~~删除线~~、`行内代码`
同一段内换行:第一句<br />第二句
<u>下划线</u>、<mark>荧光标记</mark>、<kbd>Ctrl</kbd>、H<sub>2</sub>O、x<sup>2</sup>四、列表
无序列表:
- 第一项
- 嵌套项(行首比上级多空两格)
- 另一个嵌套项
- 第二项
有序列表:
- 第一步
- 第二步
- 子步骤
- 子步骤
- 第三步
任务列表(remark-gfm 提供):
- 已完成的事项
- 未完成的事项
写法:
- 第一项
- 嵌套项
- 第二项
1. 第一步
2. 第二步
1. 子步骤
- [x] 已完成的事项
- [ ] 未完成的事项五、引用与分割线
这是一段引用文字。
引用里还可以再嵌套一层引用。
上面那条横线就是分割线。
写法:
> 这是一段引用文字。
>
> > 嵌套引用
---六、链接
- 站内链接:安装教程,写
/docs/gallery/xxx,不要带.mdx后缀。 - 站外链接:哔哩哔哩,建议新窗口打开就写
<a href="..." target="_blank">。 - 带提示文字的链接:悬停可见提示。
写法:
[安装教程](/docs/gallery/v2/install)
[哔哩哔哩](https://www.bilibili.com)
[悬停可见提示](https://www.bilibili.com "B 站首页")七、图片
普通图片(大小已由全局 CSS 统一限制在 480px 内,不用手写尺寸):

写法:
需要点击放大的图片,用 ImageZoom 组件:
写法:
<ImageZoom src="/images/xr/文件名.webp" alt="图片说明" width={480} height={640} caption="点击放大后的说明" />八、表格
| 功能 | 是否免费 | 说明 |
|---|---|---|
| 看图 | 是 | 左对齐 |
| 云同步 | 否 | 居中 |
| 离线激活 | 是 | 右对齐 |
写法(第二行的 : 决定对齐方式):
| 功能 | 是否免费 | 说明 |
| :--- | :---: | ---: |
| 看图 | 是 | 左对齐 |
| 云同步 | 否 | 居中 |九、代码块
基础代码块(反引号后写语言名,会自动高亮):
// 一个普通的 TypeScript 代码块
const siteName = 'Xr 相册';
console.log(siteName);带文件名标题:在语言名后加 title="文件名"。
// 顶部会显示文件名,并带复制按钮
export const baseUrl = '/docs';显示行号:加 lineNumbers。
// 左侧会显示 1、2、3 行号
const a = 1;
const b = 2;
const c = 3;整行高亮:在需要高亮的行尾加 // [!code highlight],也可以一次高亮多行(本示例高亮了第 2 行)。
const step1 = '准备工作';
const step2 = '执行安装';
const step3 = '完成';增删对比(diff):行尾写 // [!code ++] 表示新增,// [!code --] 表示删除。
const oldValue = 1;
const newValue = 2; 聚焦某几行(其余行变暗):行尾写 // [!code focus],连续多行会形成焦点区间。
const a = 1;
const b = 2;
const c = 3;
const d = 4;高亮某个单词:在任意行写 // [!code word:关键词],正文中所有该词都会被高亮。
const token = 'abc';
console.log(token);多标签代码块:连续写多个代码块,每块加 tab="标签名",会自动合并成标签页。
pnpm install包管理器自动切换:语言写 package-install,会自动生成 npm / pnpm / yarn / bun 四个标签页。
npm install pnpm add react行内代码:用一对反引号包住,例如 pnpm dev。
写法:代码块的写法就是上面这些代码块本身——语言名后追加 title="..."、lineNumbers,行尾写 // [!code highlight] 等标记即可。多标签用 tab="标签名"。
十、提示框 Callout
五种类型,无需引入,直接写。
info:普通说明、补充信息。
warn:警告、注意事项、容易踩坑的地方。
error:错误、失败、不可恢复的操作。
success:成功提示、已完成的验证。
idea:小技巧、灵感、优化建议。
自定义标题
加上 title 属性可以自定义标题。
写法:
<Callout type="info">
内容写在这里,支持加粗、链接、列表等。
</Callout>
<Callout type="warn" title="自定义标题">
内容写在这里。
</Callout>十一、卡片 Card / Cards
写法(外层 Cards 包住多个 Card):
<Cards>
<Card title="标题" href="/docs/gallery/v2/install" description="一句话描述" />
<Card title="标题" href="/docs/gallery/v2/about" description="一句话描述" />
</Cards>十二、步骤 Steps
写法(Step 内要留空行,才能正常解析里面的标题和段落):
<Steps>
<Step>
### 第一步
内容。
</Step>
<Step>
### 第二步
内容。
</Step>
</Steps>十三、标签页 Tabs
Windows 下打开「设备管理器」,确认设备已连接。
写法:
<Tabs items={['Windows', 'macOS']}>
<Tab value="Windows">
内容。
</Tab>
<Tab value="macOS">
内容。
</Tab>
</Tabs>十四、折叠面板 Accordions
一般是压缩得太小或图片过大,请重新压缩后上传。
请把手环端和手机端都升级到最新版后重新上传。
写法:
<Accordions>
<Accordion title="标题一">
内容。
</Accordion>
<Accordion title="标题二">
内容。
</Accordion>
</Accordions>十五、文件树 Files
写法(defaultOpen 表示默认展开):
<Files>
<Folder name="content" defaultOpen>
<File name="index.mdx" />
<Folder name="docs">
<File name="meta.json" />
</Folder>
</Folder>
</Files>十六、参数表 TypeTable
属性
类型
写法(对象里的键就是参数名):
<TypeTable
type={{
title: {
description: '页面标题,必填。',
type: 'string',
required: true,
},
full: {
type: 'boolean',
default: 'false',
},
}}
/>十七、横幅 Banner
这是一条横幅演示,changeLayout 为 false 表示不改变整页布局高度。
写法(一般放在 app/docs/gallery/layout.tsx 顶部,正文里只做演示用):
<Banner variant="normal" changeLayout={false}>
横幅文字
</Banner>十八、注释
MDX 里的注释必须写成 JSX 注释,不能用 <!-- -->,否则会编译报错。
写法:
{/* 注释内容,不会渲染到页面 */}十九、特殊符号转义
MDX 会把 { 和 } 当成代码表达式,正文里出现花括号要转义:{花括号};星号想显示原样也加反斜杠:*不是斜体*。
写法:
\{花括号\}、\*不是斜体\*二十、一页完整模板
把下面这段复制到新建的 .mdx 文件里,改内容即可(记得在同目录 meta.json 的 pages 里加上文件名)。
---
title: "新页面标题"
description: "一句话简介"
---
> 导语:这一页解决什么问题。
**开始之前**:需要准备什么。
## 一、第一步
<Callout type="info">
补充说明放这里。
</Callout>
1. 打开某某界面。
2. 点击某某按钮。

## 二、第二步
<Callout type="warn">
注意事项放这里。
</Callout>
完成后前往 [下一页](/docs/gallery/v2/next-page) 继续。