My Docs

Appearance

Markdown 格式示例 ​

本页集中展示 VitePress 支持的**标准 Markdown（CommonMark / GFM）**语法。

每个示例都按三部分呈现：语法说明（是什么 / 怎么用）→ 示例写法（原始 Markdown 源码）→ 实际效果（渲染后的样子）。

1. 标题 ​

语法说明：用 # ~ ###### 表示一级到六级标题，井号数量对应层级。

示例写法：

md
# 一级标题 H1
## 二级标题 H2
### 三级标题 H3
#### 四级标题 H4
##### 五级标题 H5
###### 六级标题 H6

实际效果：

一级标题 H1 ​

二级标题 H2 ​

三级标题 H3 ​

四级标题 H4 ​

五级标题 H5 ​
六级标题 H6 ​

2. 文本样式 ​

语法说明：星号 / 波浪号 / 等号包裹文本实现加粗、斜体、删除线、高亮等样式。

示例写法：

md
**加粗**  *斜体*  ***加粗斜体***  ~~删除线~~  ==高亮==

实际效果：

加粗 斜体 加粗斜体 删除线 ==高亮==

3. 行内代码 ​

语法说明：用反引号包裹表示行内代码，不会被渲染为格式。

示例写法：

md
使用 `pnpm install` 安装依赖，再执行 `pnpm docs:dev` 启动。

实际效果：

使用 pnpm install 安装依赖，再执行 pnpm docs:dev 启动。

4. 上下标 ​

语法说明：用 ~ 包裹下标、^ 包裹上标（VitePress 基于 markdown-it-sub / sup 支持）。

示例写法：

md
水的化学式 H~2~O，质能方程 E = mc^2^。

实际效果：

水的化学式 H~2~O，质能方程 E = mc^2^。

5. 键盘按键 ​

语法说明：用 HTML 的 <kbd> 标签渲染键盘按键样式。

示例写法：

md
按 <kbd>Ctrl</kbd> + <kbd>K</kbd> 唤起全站搜索。

实际效果：

按 Ctrl + K 唤起全站搜索。

6. 段落与换行 ​

语法说明：段落之间空一行分隔；行尾加两个空格再换行是「软换行」（同一段内换行）。

示例写法：

md
这是第一段。

这是第二段（中间空一行）。

软换行在行尾加两个空格  
来实现。

实际效果：

这是第一段。

这是第二段（中间空一行）。

软换行在行尾加两个空格
来实现。

7. 引用 ​

语法说明：用 > 开头表示引用块，> 后接空行再 > 可实现嵌套引用。

示例写法：

md
> 外层引用
>
> > 内层引用（嵌套）

实际效果：

外层引用

内层引用（嵌套）

8. 列表 ​

语法说明：- / * 表示无序列表，1. 表示有序列表；缩进两格表示嵌套。

示例写法：

md
- 水果
  - 苹果
  - 香蕉
- 蔬菜

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

实际效果：

  • 水果
    • 苹果
    • 香蕉
  • 蔬菜
  1. 第一步
  2. 第二步
    1. 子步骤

9. 任务列表 ​

语法说明：在列表项前用 [ ]（未完成）或 [x]（已完成）表示复选框，GFM 扩展语法。

示例写法：

md
- [x] 已完成任务
- [ ] 未完成任务
- [ ] 待办事项

实际效果：

  • [x] 已完成任务
  • [ ] 未完成任务
  • [ ] 待办事项

10. 定义列表 ​

语法说明：术语单独一行，下一行用 : 开头给出定义；多个 : 行表示多个含义。

示例写法：

md
Markdown
: 轻量级标记语言。

VitePress
: 基于 Vite 的静态站点生成器。
: 专为文档场景设计。

实际效果：

Markdown : 轻量级标记语言。

VitePress : 基于 Vite 的静态站点生成器。 : 专为文档场景设计。

11. 代码块 ​

语法说明：用三个反引号包裹，并标注语言即可获得语法高亮；不带语言则为纯文本。

示例写法：

md
```ts
interface User {
  id: number
  name: string
}

function greet(user: User): string {
  return `Hello, ${user.name}!`
}
```

实际效果：

ts
interface User {
  id: number
  name: string
}

function greet(user: User): string {
  return `Hello, ${user.name}!`
}

12. 表格 ​

语法说明：用 | 分隔列，第二行用 - 画分隔线；冒号控制对齐方式（:--- 左、---: 右、:---: 中）。

示例写法：

md
| 名称   | 类型   | 是否推荐 |
| :----- | :----: | -------: |
| 苹果   | 水果   |      是 |
| 胡萝卜 | 蔬菜   |      是 |

实际效果：

名称类型是否推荐
苹果水果是
胡萝卜蔬菜是

13. 链接 ​

语法说明：[文本](地址) 创建链接；支持外部地址、站内绝对路径、锚点（#标题）、邮件 mailto:；也可用原生 HTML 控制新窗口打开。

示例写法：

md
- 外部：[VitePress 官网](https://vitepress.dev)
- 站内：[/guide/getting-started](/guide/getting-started)
- 锚点：[跳到「表格」](#12-表格)
- 邮件：[发送邮件](mailto:hello@example.com)
- 新窗口：<a href="https://vitepress.dev" target="_blank">VitePress（新窗口）</a>

实际效果：

14. 图片 ​

语法说明：![替代文本](路径) 插入图片。本文档图片放在同目录，用相对路径 ./logo.svg 引用；放在 docs/.vitepress/public/ 的资源则用 /logo.svg 引用。点击图片可放大（参见「插件应用示例」页的 medium-zoom），加 .no-zoom 类可禁用缩放。

示例写法：

md
![Logo](/logo.svg)

![不缩放的 Logo](/logo.svg){.no-zoom}

实际效果（下图可点击放大，本页已接入 medium-zoom）：

Logo

15. 脚注 ​

语法说明：正文用 [^标签]，文末用 [^标签]: 解释 定义脚注，GFM 扩展语法。

⚠️ 注意：VitePress 默认未内置脚注插件。下方仅展示语法，需安装 markdown-it-footnote 并在 markdown.config 中调用 md.use(footnote) 后才会真正渲染到页面底部。

示例写法：

md
这是带脚注的句子。[^1] 还有另一个引用。[^note]

[^1]: 脚注内容一，出现在页面底部。
[^note]: 脚注内容二，标签可为任意字母数字。

16. 表情符号（Emoji 短码） ​

语法说明：用 :短码: 插入表情，VitePress 内置 emoji 支持。

示例写法：

md
:rocket: :sparkles: :warning: :heart: :tada:

实际效果：

🚀 ✨ ⚠️ ❤️ 🎉

17. 水平分割线 ​

语法说明：单独一行的三个或以上连字符 --- 渲染为分隔线。

示例写法：

md
上方内容

---

下方内容

实际效果：

上方内容

下方内容

18. 转义字符 ​

语法说明：用反斜杠 \ 转义 Markdown 特殊字符，使其按原样显示。

示例写法：

md
\*这不是斜体\*，\#这不是标题，\`这不是代码\`。

实际效果：

*这不是斜体*，#这不是标题，`这不是代码`。

19. 原生 HTML ​

语法说明：Markdown 中可直接书写 HTML，可借助内联样式实现任意排版。

示例写法：

md
这是 <strong>加粗的原生 HTML</strong>。

<div style="padding:8px 12px;border:1px dashed var(--vp-c-border);border-radius:8px;">
用原生 HTML 渲染的内容，可使用任意内联样式。
</div>

实际效果：

这是 加粗的原生 HTML。

用原生 HTML 渲染的内容，可使用任意内联样式。

20. 注释 ​

语法说明：HTML 注释 <!-- --> 只在源码中可见，不会被渲染到页面。

示例写法：

md
<!-- 这是一段注释，读者看不到 -->

实际效果（下面整行不会显示任何内容）：

21. 字符实体 ​

语法说明：HTML 字符实体可用于显示特殊符号，如 &amp;、&lt;、&copy;。

示例写法：

md
&copy; 2026 &amp; &lt;tag&gt; &nbsp;不换行空格

实际效果：

© 2026 & <tag>  不换行空格