寻日文档

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>

四、列表

无序列表:

  • 第一项
    • 嵌套项(行首比上级多空两格)
    • 另一个嵌套项
  • 第二项

有序列表:

  1. 第一步
  2. 第二步
    1. 子步骤
    2. 子步骤
  3. 第三步

任务列表(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 内,不用手写尺寸):

安装过程示例

写法:

![图片说明文字](/images/xr/文件名.webp)

需要点击放大的图片,用 ImageZoom 组件:

可放大的示例图

写法:

<ImageZoom src="/images/xr/文件名.webp" alt="图片说明" width={480} height={640} caption="点击放大后的说明" />

八、表格

功能是否免费说明
看图是左对齐
云同步否居中
离线激活是右对齐

写法(第二行的 : 决定对齐方式):

| 功能 | 是否免费 | 说明 |
| :--- | :---: | ---: |
| 看图 | 是 | 左对齐 |
| 云同步 | 否 | 居中 |

九、代码块

基础代码块(反引号后写语言名,会自动高亮):

// 一个普通的 TypeScript 代码块
const siteName = 'Xr 相册';
console.log(siteName);

带文件名标题:在语言名后加 title="文件名"。

lib/config.ts
// 顶部会显示文件名,并带复制按钮
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

index.mdx
package.json

写法(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. 点击某某按钮。

![操作截图](/images/xr/xxxx.webp)

## 二、第二步

<Callout type="warn">
注意事项放这里。
</Callout>

完成后前往 [下一页](/docs/gallery/v2/next-page) 继续。

© 2026 寻日文档 · 内容版权归寻日穿戴所有。

文档内容以实际发布版本为准 · 官方网站 · 图库网站

本页目录